Skip to content

frames.js

npm install frames.js
frames.js is the fastest way to make Frames.

What's in frames.js?

  • ⚡️ Local frames debugger
  • 🥳 Write Frames using React
  • 🔋 Batteries included framework
  • 🌴 Tree-shakeable & Lightweight
  • 🚀 Library with all the functions

Quickstart

1. Clone the frames.js starter template (with local debugger)

Run to clone the starter into a new folder called framesjs-starter

npx degit github:framesjs/frames.js/examples/framesjs-starter#main framesjs-starter

or clone from github

Alternatively, add frames.js to your existing project manually

Start with frames.js in Next.js in two copy-pastes

// ./app/page.tsx
 
import { FrameContainer, FrameImage, FrameButton, getFrameMessage, useFramesReducer, getPreviousFrame, validateActionSignature, FrameInput } from "frames.js/next/server";
 
const reducer = (state, action) => ({ count: state.count + 1 });
 
export default async function Home(props) {
  const previousFrame = getPreviousFrame(props.searchParams);
  const frameMessage = await getFrameMessage(previousFrame.postBody);
 
  if (frameMessage && !frameMessage?.isValid) {
    throw new Error("Invalid frame payload");
  }
  const [state, dispatch] = useFramesReducer(reducer, { count: 0 }, previousFrame);
 
  return (
    <FrameContainer postUrl="/frames" state={state} previousFrame={previousFrame}>
      <FrameImage>
        <div tw="w-full h-full bg-slate-700 text-white justify-center items-center">
          {state.count}
        </div>
      </FrameImage>
      <FrameButton onClick={dispatch}>{state.count}</FrameButton>
    </FrameContainer>
  );
}
// ./app/frames/route.ts
 
export { POST } from "frames.js/next/server";

Community

Check out the following places for more Frames-related content:

Local fully interactive Debugger & Frame validation

Or use the hosted Frames debugger. Running locally has the benefits of it working with natively with localhost.

Prefer to not use JSX?

Use frames.js in Next.js using helper functions

// page that renders a frame
// ./app/page.tsx
 
import { Frame, getFrameFlattened } from "frames.js";
import type { Metadata } from "next";
 
// Declare the frame
const initialFrame: Frame = {
  image: "https://picsum.photos/seed/frames.js/1146/600",
  version: "vNext",
  buttons: [
    {
      label: "Random image",
    },
  ],
  postUrl: `${process.env.NEXT_PUBLIC_HOST}/frames`,
};
 
// Export Next.js metadata
export const metadata: Metadata = {
  title: "Random Image Frame",
  description: "This is an example of a simple frame using frames.js",
  openGraph: {
    images: [
      {
        url: "https://picsum.photos/seed/frames.js/600",
      },
    ],
  },
  other: getFrameFlattened(initialFrame),
};
// handle frame actions
// ./app/frames/route.ts
 
import { getFrameHtml, validateFrameMessage } from "frames.js";
import { NextRequest } from "next/server";
 
export async function POST(request: NextRequest) {
  const body = await request.json();
 
  // Parse and validate the frame message
  const { isValid, message } = await validateFrameMessage(body);
  if (!isValid || !message) {
    return new Response("Invalid message", { status: 400 });
  }
 
  const randomInt = Math.floor(Math.random() * 100);
  const imageUrlBase = `https://picsum.photos/seed/${randomInt}`;
 
  // Use the frame message to build the frame
  const frame = {
    version: "vNext",
    image: `${imageUrlBase}/1146/600`,
    buttons: [
      {
        label: `Next (pressed by ${message.data.fid})`,
      },
    ],
    ogImage: `${imageUrlBase}/600`,
    postUrl: `${process.env.NEXT_PUBLIC_HOST}/frames`,
  };
 
  // Return the frame as HTML
  const html = getFrameHtml(frame);
 
  return new Response(html, {
    headers: {
      "Content-Type": "text/html",
    },
    status: 200,
  });
}

Source Code

The source code for frames.js is available on GitHub

frames.js is distributed under an MIT License.

We welcome contributions from the community. If you would like to contribute, please open an issue or a pull request.

Feel free to ask any questions on /frames-devs and tag @frames