diff --git a/.changeset/four-cheetahs-tease.md b/.changeset/four-cheetahs-tease.md
new file mode 100644
index 000000000..704a31c10
--- /dev/null
+++ b/.changeset/four-cheetahs-tease.md
@@ -0,0 +1,5 @@
+---
+"docs": patch
+---
+
+docs: improve farcasterHubContext docs
diff --git a/docs/pages/middleware/farcasterHubContext.mdx b/docs/pages/middleware/farcasterHubContext.mdx
index 3c3a10907..55ab98fa9 100644
--- a/docs/pages/middleware/farcasterHubContext.mdx
+++ b/docs/pages/middleware/farcasterHubContext.mdx
@@ -2,9 +2,11 @@
 
 Fetches additional context about the message from a Farcaster hub.
 
-## Usage
+## Setup
+
+Add the `farcasterHubContext` middleware to your `createFrames` call:
 
-```tsx
+```tsx [frames.ts]
 // ...
 import { farcasterHubContext } from "frames.js/middleware";
 
@@ -18,6 +20,26 @@ const frames = createFrames({
 });
 ```
 
+## Usage
+
+Use the added context in your message handler:
+
+```tsx [route.tsx]
+import { frames } from "./frames";
+
+export const POST = frames(async (ctx) => {
+  if (!ctx.message?.isValid) {
+    throw new Error("Invalid message");
+  }
+
+  return {
+    image: <div tw="flex">Message from {ctx.message?.requesterFid}</div>,
+  };
+});
+```
+
+For all the added context see the [`getFrameMessage`](/reference/js/getFrameMessage) function reference.
+
 ## Options
 
 ### `hubHttpUrl`