...
,
+ imageOptions: {
+ width: 100,
+ height: 100,
+ },
+};
+```
+
+### Image wrong format
+
+If the image is not rendering, it may be in the wrong format. SVG images are typically not supported on mobile.
+
+## Initial frame not loading
+
+Ensure that the `fetchMetadata` URL is correct and that it is inside the `other` folder for Next.js.
+
+### `VERCEL_URL` environment variable
+
+If you are using Vercel, the `VERCEL_URL` environment variable is not a fully qualified URL and may cause issues with `fetchMetadata`. You will have to prepend the protocol `VERCEL_URL`.
+
+```tsx
+export async function generateMetadata() {
+ const frameMetadata = await fetchMetadata(
+ new URL(
+ "/frames",
+ process.env.VERCEL_URL
+ ? `https://${process.env.VERCEL_URL}`
+ : "http://localhost:3000"
+ )
+ );
+
+ return {
+ title: "My page",
+ other: {
+ ...frameMetadata,
+ },
+ };
+}
+```
+
+### Vercel authentication
+
+When deploying to Vercel, your site will not automatically be accessible to the public. You will need to disable Vercel Authentication under `Settings > Deployment Protection > Vercel Authentication`
+
+## Import type errors
+
+If you are getting type errors when importing `frames.js`, you may need to change the `moduleResolution` in your `tsconfig.json` from `node` to `nodenext`.
+
+```json
+{
+ "compilerOptions": {
+ "moduleResolution": "nodenext"
+ }
+}
+```
+
+## Unable to access frame message on initial frame
+
+The initial frame is accessed via a GET request and does not have access to frame message and hence user data.
+
+## Type error: Route ... does not match the required types of a Next.js Route
+
+If you are getting this error you are exporting something other than a Next.js route from a `route.tsx` or `page.tsx` file.
+
+We recommend creating a new file for your `frames` app and importing it in the routes that use it.
+
+### Example
+
+Frames app file
+
+```tsx [frames.ts]
+import { createFrames } from "frames.js/next";
+
+export const frames = createFrames({
+ basePath: "/frames",
+});
+```
+
+Initial page route
+
+```tsx [route.tsx]
+import { frames } from "./frames";
+
+export const GET = frames(async (ctx) => {
+ // ctx.message is not available in the initial frame
+ return {
+ image: ...
,
+ buttons: [
+ ,
+ ],
+ };
+});
+```
+
+Frame action handler route
+
+```tsx [my-route/route.tsx]
+import { frames } from "../frames";
+
+export const POST = frames(async (ctx) => {
+ // Do something with ctx.message
+ // ...
+
+ return {
+ image: ...
,
+ buttons: [
+ // ...
+ ],
+ };
+});
+```
+
+## Combining old and new SDKs
+
+You cannot use the `The user's username is {ctx.message.requesterUserData.username}
+ ),
+ };
+});
+```
+
+### Per-route middleware
+
+You can also specify middleware per-route that will only be applied to that route:
+
+```tsx [frames/username/route.tsx]
+import { farcasterHubContext } from "frames.js/middleware";
+
+export const POST = frames(
+ async (ctx) => {
+ // The added context from the middleware will be available on `ctx` here
+ if (!ctx.message.isValid) {
+ throw new Error("Invalid message");
+ }
+
+ return {
+ image: (
+
+ The user's username is {ctx.message.requesterUserData.username}
+
+ ),
+ };
+ },
+ {
+ middleware: [farcasterHubContext()],
+ }
+);
+```
+
+## Defining your own middleware
+
+You can define your own middleware by creating a function that returns a promise that resolves to the next middleware, or a [Web API `Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response), or a `FrameDefinition`.
+
+Middleware can modify the context or return a response that will terminate the request early.
+
+### Adding context
+
+:::code-group
+
+```tsx [frames.ts]
+import { createFrames, types } from "frames.js/next";
+
+const myMiddleware: types.FramesMiddleware<
+ any,
+ { foo: string }
+> = async (ctx, next) => {
+ return next({ foo: "bar" });
+};
+
+export const frames = createFrames({
+ basePath: "/",
+ initialState: {
+ pageIndex: 0,
+ },
+ // Add the middleware
+ middleware: [myMiddleware],
});
-```
\ No newline at end of file
+```
+
+```tsx [frames/route.tsx]
+import { Button } from "frames.js/next";
+import { frames } from "./frames";
+
+const handler = frames(async (ctx) => {
+ return {
+ // Use the additional contect
+ image: foo: ${ctx.bar}
,
+ };
+});
+
+export const GET = handler;
+export const POST = handler;
+```
+
+:::
diff --git a/docs/pages/reference/core/Button.mdx b/docs/pages/reference/core/Button.mdx
index 7fad906b4..919aefccf 100644
--- a/docs/pages/reference/core/Button.mdx
+++ b/docs/pages/reference/core/Button.mdx
@@ -123,7 +123,7 @@ const export frames = createFrames()
export const GET = frames(async (ctx) => {
return {
image: (
-
+ `.
+
+```tsx
+import { createFrames, types } from "frames.js/next";
+
+const myMiddleware: types.FramesMiddleware<
+ any,
+ { foo?: string }
+> = async (ctx, next) => {
+ return next({ foo: "bar" });
+};
+```
+
#### Example
```tsx [./app/frames/route.tsx]
@@ -48,7 +65,7 @@ const frames = createFrames({
middleware: [
async (ctx, next) => {
console.log("Before frame handler");
- const result = await next({name: "Alice"});
+ const result = await next({ name: "Alice" });
console.log("After frame handler");
return result;
},
@@ -167,15 +184,16 @@ handleRequest(new Request("/")).then((res) => {
You can also pass middleware to the `handleRequest` function to be executed only for that specific route.
```tsx
-const handleRequest = frames(async (ctx) => {
- return {
- image: Test,
- };
-}, {
- middleware: [
- farcasterHubContext({ hubHttpUrl: process.env.HUB_HTTP_URL }),
- ]
-});
+const handleRequest = frames(
+ async (ctx) => {
+ return {
+ image: Test,
+ };
+ },
+ {
+ middleware: [farcasterHubContext({ hubHttpUrl: process.env.HUB_HTTP_URL })],
+ }
+);
```
This will only execute the `farcasterHubContext` middleware for the route that `handleRequest` is called with.
@@ -243,7 +261,3 @@ The client protocol that was used to send the frame message.
- Type: `JsonValue`
The state extracted from the frame message. If you are on the initial frame (no button pressed), the value is the `initialState` value passed to `createFrames`. If you are on a frame with a button pressed, the value is the state from the previous frame.
-
-
-
-
diff --git a/docs/pages/troubleshooting.mdx b/docs/pages/troubleshooting.mdx
index 53333f68a..27ad5ca51 100644
--- a/docs/pages/troubleshooting.mdx
+++ b/docs/pages/troubleshooting.mdx
@@ -60,7 +60,7 @@ export async function generateMetadata() {
### Vercel authentication
-When deploying to Vercel, your site will not automatically be accessible to the public. You will need to disable Vercel Authentication under `Settings > Deployment Protection > Vercel Authentication`
+When deploying to Vercel, your site will not automatically be accessible to the public. You will need to disable Vercel Authentication under your project's `Settings > Deployment Protection > Vercel Authentication` on vercel.com.
## Import type errors
From 1a68dc5014acb9f01d4113ce4a53bbadcd89d2c7 Mon Sep 17 00:00:00 2001
From: Stephan Cilliers <5469870+stephancill@users.noreply.github.com>
Date: Tue, 26 Mar 2024 17:44:08 +0200
Subject: [PATCH 10/18] fix: update use-frame docs
---
docs/pages/reference/render/use-frame.mdx | 153 +++++++++++++++++++---
1 file changed, 135 insertions(+), 18 deletions(-)
diff --git a/docs/pages/reference/render/use-frame.mdx b/docs/pages/reference/render/use-frame.mdx
index 299b47d86..dc0115491 100644
--- a/docs/pages/reference/render/use-frame.mdx
+++ b/docs/pages/reference/render/use-frame.mdx
@@ -2,24 +2,141 @@
## Props
-```ts
-type Props = {
- /** the route used to POST frame actions. The post_url will be added as a the `url` query parameter */
- frameActionProxy: string;
- /** the route used to GET the initial frame via proxy */
- frameGetProxy: string;
- /** an auth state object used to determine what actions are possible */
- signerState: SignerStateInstance;
- /** the url of the homeframe, if null won't load a frame */
- homeframeUrl: string | null;
- /** the initial frame. if not specified will fetch it from the url prop */
- frame?: Frame;
- /** a function to handle mint buttons */
- onMint?: (t: onMintArgs) => void;
- /** the context of this frame, used for generating Frame Action payloads */
- frameContext: FrameContext;
-};
-```
+### `dangerousSkipSigning`
+
+- Type: `boolean`
+
+If true, the frame will not be signed before being sent to the frameActionProxy. This is useful for frames that don't verify signatures.
+
+### `frameActionProxy`
+
+- Type: `string`
+
+The route used to POST frame actions. The post_url will be added as a the `url` query parameter.
+
+### `frameGetProxy`
+
+- Type: `string`
+
+The route used to GET the initial frame via proxy.
+
+### `signerState`
+
+- Type: `SignerStateInstance`
+
+An signer state object used to determine what actions are possible.
+
+### `homeframeUrl`
+
+- Type: `string | null`
+
+The url of the homeframe, if null won't load a frame.
+
+### `frame`
+
+- Type: `Frame`
+
+The initial frame. if not specified will fetch it from the url prop.
+
+### `onMint`
+
+- Type: `(t: onMintArgs) => void`
+
+A function to handle mint buttons.
+
+### `onTransaction`
+
+- Type: `OnTransactionFunc`
+
+A function to handle transaction button presses, returns the transaction hash or null.
+
+### `frameContext`
+
+- Type: `FrameContext`
+
+The context of this frame, used for generating Frame Action payloads.
+
+### `extraButtonRequestPayload`
+
+- Type: `Record`
+
+Extra data appended to the frame action payload.
+
+## Returns
+
+- Type: `FrameState`
+
+### `fetchFrame`
+
+- Type: `(request: FrameRequest) => void`
+
+Fetches a frame from the frameGetProxy.
+
+### `clearFrameStack`
+
+- Type: `() => void`
+
+Clears the frame stack.
+
+### `frame`
+
+- Type: `Frame | null`
+
+The frame at the top of the stack (at index 0).
+
+### `framesStack`
+
+- Type: `FramesStack`
+
+A stack of frames with additional context, with the most recent frame at index 0.
+
+### `isLoading`
+
+- Type: `null | FrameStackPending`
+
+Whether the frame is loading.
+
+### `inputText`
+
+- Type: `string`
+
+The input text.
+
+### `setInputText`
+
+- Type: `(s: string) => void`
+
+Sets the input text.
+
+### `onButtonPress`
+
+- Type: `(frameButton: FrameButton, index: number) => void`
+
+Handles a button press.
+
+### `isFrameValid`
+
+- Type: `boolean | undefined`
+
+Whether the frame at the top of the stack has any frame validation errors. Undefined when the frame is not loaded or set.
+
+### `frameValidationErrors`
+
+- Type: `Record | undefined | null`
+
+The frame validation errors.
+
+### `error`
+
+- Type: `null | unknown`
+
+Whether there was an error loading the frame.
+
+### `homeframeUrl`
+
+- Type: `string | null`
+
+The url of the frame.
## Usage
From 22ad5850e072a7567a555a2795a3f6fb0d66f6d9 Mon Sep 17 00:00:00 2001
From: Stephan Cilliers <5469870+stephancill@users.noreply.github.com>
Date: Wed, 27 Mar 2024 10:31:31 +0200
Subject: [PATCH 11/18] chore: move old apis to a deprecated apis section
---
docs/vocs.config.tsx | 117 ++++++++++++++++++++++---------------------
1 file changed, 61 insertions(+), 56 deletions(-)
diff --git a/docs/vocs.config.tsx b/docs/vocs.config.tsx
index e3eccd0ec..f79d9b67f 100644
--- a/docs/vocs.config.tsx
+++ b/docs/vocs.config.tsx
@@ -185,62 +185,6 @@ const sidebar = [
},
],
},
- {
- text: "frames.js/next/server",
- collapsed: true,
- items: [
- {
- text: "getPreviousFrame",
- link: "/reference/nextjs/getPreviousFrame",
- },
- {
- text: "POST",
- link: "/reference/nextjs/POST",
- },
- ],
- },
- {
- text: "frames.js/next/server - [react]",
- collapsed: true,
- items: [
- {
- text: "types",
- link: "/reference/react/types",
- },
- {
- text: "FrameContainer",
- link: "/reference/react/FrameContainer",
- },
- {
- text: "FrameButton",
- link: "/reference/react/FrameButton",
- },
- {
- text: "FrameImage",
- link: "/reference/react/FrameImage",
- },
- {
- text: "FrameInput",
- link: "/reference/react/FrameInput",
- },
- {
- text: "parseFrameParams",
- link: "/reference/react/parseFrameParams",
- },
- {
- text: "useFramesReducer",
- link: "/reference/react/useFramesReducer",
- },
- {
- text: "validateActionSignature",
- link: "/reference/react/validateActionSignature",
- },
- {
- text: "createPreviousFrame",
- link: "/reference/react/createPreviousFrame",
- },
- ],
- },
{
text: "@frames.js/render",
collapsed: true,
@@ -277,6 +221,67 @@ const sidebar = [
},
],
},
+ {
+ text: "Deprecated APIs",
+ items: [
+ {
+ text: "frames.js/next/server",
+ collapsed: true,
+ items: [
+ {
+ text: "getPreviousFrame",
+ link: "/reference/nextjs/getPreviousFrame",
+ },
+ {
+ text: "POST",
+ link: "/reference/nextjs/POST",
+ },
+ ],
+ },
+ {
+ text: "frames.js/next/server - [react]",
+ collapsed: true,
+ items: [
+ {
+ text: "types",
+ link: "/reference/react/types",
+ },
+ {
+ text: "FrameContainer",
+ link: "/reference/react/FrameContainer",
+ },
+ {
+ text: "FrameButton",
+ link: "/reference/react/FrameButton",
+ },
+ {
+ text: "FrameImage",
+ link: "/reference/react/FrameImage",
+ },
+ {
+ text: "FrameInput",
+ link: "/reference/react/FrameInput",
+ },
+ {
+ text: "parseFrameParams",
+ link: "/reference/react/parseFrameParams",
+ },
+ {
+ text: "useFramesReducer",
+ link: "/reference/react/useFramesReducer",
+ },
+ {
+ text: "validateActionSignature",
+ link: "/reference/react/validateActionSignature",
+ },
+ {
+ text: "createPreviousFrame",
+ link: "/reference/react/createPreviousFrame",
+ },
+ ],
+ },
+ ],
+ },
],
},
];
From db8e61257f951570af3c6c7a999a1cf65d0e65f1 Mon Sep 17 00:00:00 2001
From: Stephan Cilliers <5469870+stephancill@users.noreply.github.com>
Date: Wed, 27 Mar 2024 10:33:31 +0200
Subject: [PATCH 12/18] fix: make button docs more visible, multi-page docs
---
docs/pages/guides/create-frame.mdx | 19 ++-
docs/pages/guides/multiple-frames.mdx | 185 ++++++++++++++++++++------
docs/pages/reference/core/Button.mdx | 18 ++-
3 files changed, 172 insertions(+), 50 deletions(-)
diff --git a/docs/pages/guides/create-frame.mdx b/docs/pages/guides/create-frame.mdx
index f6e9fbae4..3e29ef334 100644
--- a/docs/pages/guides/create-frame.mdx
+++ b/docs/pages/guides/create-frame.mdx
@@ -8,7 +8,9 @@ description: "Frames.js is the react based framework for making frames. Debugger
This guide shows you how to add frames rendering to your next.js + tailwind app using frames.js.
## Steps
+
::::steps
+
### Create a new repo
Create a new Next.js app
@@ -24,7 +26,6 @@ Add `frames.js` to your project
yarn add frames.js
```
-
### Create your Frames app
```tsx [./app/frames/frames.ts]
@@ -34,6 +35,7 @@ export const frames = createFrames();
```
### Create a route
+
```tsx [./app/frames/route.tsx]
/* eslint-disable react/jsx-key */
import { Button } from "frames.js/next";
@@ -49,10 +51,10 @@ const handleRequest = frames(async (ctx) => {
),
buttons: [
-
Execute transaction
),
diff --git a/docs/pages/reference/core/createFrames.mdx b/docs/pages/reference/core/createFrames.mdx
index c30ea287d..9cbdde563 100644
--- a/docs/pages/reference/core/createFrames.mdx
+++ b/docs/pages/reference/core/createFrames.mdx
@@ -35,12 +35,29 @@ A JSON serializable value that is used if no state is provided in the message or
### `middleware`
+See the [Middleware guide](/guides/middleware) for more information.
+
Type: `FramesMiddleware`
An array of middleware functions that are called before the frame handler and allows you to inject additional context into the `ctx` parameter passed to each frame handler call.
Each middleware should return a promise that resolves to the next middleware, or a [Web API `Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response), or a `FrameDefinition`.
+#### Types
+
+For strong type support in the handler, the middleware should be typed as `FramesMiddleware