Skip to content
Github

Images Worker

The images worker serializes JSX images in frame definition responses into a URL which is rendered in a separate request and not bound by data URL size limits.

It does this by serializing the JSX component tree into a string which is passed to the image worker route via a query param in a URL. The worker deserializes the JSX and renders it into a PNG image as a separate response.

Usage in Next.js

Set up the images worker endpoint

Optionally specify a secret to secure the endpoint.

./images/route.tsx
import { createImagesWorker } from "frames.js/middleware/images-worker/next";
 
const imagesRoute = createImagesWorker({
  secret: "SOME_SECRET_VALUE",
});
 
export const GET = imagesRoute();

Add the imagesWorkerMiddleware middleware to your Frames app

./frames/frames.ts
import { createFrames } from "frames.js/next";
import { imagesWorkerMiddleware } from "frames.js/middleware/images-worker"; 
 
export const frames = createFrames({
  // ...
  middleware: [

    imagesWorkerMiddleware({

      imageRoute: "/images", 
      secret: "SOME_SECRET_VALUE", 
    }), 
  ], 
});

See the basic images worker example for a complete example.

Usage in Cloudflare Workers

Create images worker handler

Optionally specify a secret to secure the endpoint.

./src/images-worker.ts
import { createImagesWorkerRequestHandler } from "frames.js/middleware/images-worker/handler";
 
export const handleImagesWorkerRequest = createImagesWorkerRequestHandler({
  secret: "SOME_SECRET_VALUE",
});

Add the imagesWorkerMiddleware middleware to your Frames app

./src/frames.tsx
import { createFrames } from "frames.js/cloudflare-worker";
import { imagesWorkerMiddleware } from "frames.js/middleware/images-worker";
 
export const frames = createFrames({
  // ...
  middleware: [
    imagesWorkerMiddleware({
      imageRoute: "/images",
      secret: "SOME_SECRET_VALUE",
    }),
  ],
});
 
export const handleFramesRequest = frames(async () => {
  return {
    image: <span>Hello, World!</span>,
  };
});

Create a Cloudflare Worker handler

./src/index.ts
import { handleFramesRequest } from "./frames";
import { handleImagesWorkerRequest } from "./images-worker";
 
export default {
  async fetch(req, env, ctx) {
    const url = new URL(req.url);
 
    if (url.pathname === "/images") {
      return handleImagesWorkerRequest(req);
    }
 
    return handleFramesRequest(req, env, ctx);
  },
} satisfies ExportedHandler;

See the Cloudflare Worker with custom images worker example for a complete example.

imagesWorkerMiddleware Options

secret

  • Type: string
  • Default: undefined

A secret value to sign the serialized JSX string with. This is used to prevent unauthorized requests to the images worker endpoint.

imageRoute

  • Type: string

The route to the images worker endpoint. Should be an absolute URL or a path relative to the root of the app.

createImagesWorkerRequestHandler() - Options

secret

  • Type: string
  • Default: undefined

If defined it will only render images with a valid signature that was produced by the same secret. Should match the secret value passed to the imagesWorkerMiddleware middleware.

imageOptions

Options passed to the default image renderer which is used to render the JSX into a PNG image, @vercel/og.

jsxToResponse

  • Type: (jsx: ReactElement, options?: { aspectRatio: ImageAspectRatio }) => Promise<Response>
  • Default: undefined

A function that takes a JSX element and returns a response. By default, it uses the @vercel/og image renderer to render the JSX into a PNG image. The renderer should respect the aspectRatio option if it is provided.

See the custom images worker example for an example of how to specify a custom renderer.

createImagesWorker() - Options

secret

  • Type: string
  • Default: undefined

If defined it will only render images with a valid signature that was produced by the same secret. Should match the secret value passed to the imagesWorkerMiddleware middleware.

imageOptions

Options passed to the default image renderer which is used to render the JSX into a PNG image, @vercel/og.

jsxToResponse

  • Type: (jsx: ReactElement, options?: { aspectRatio: ImageAspectRatio }) => Promise<Response>
  • Default: undefined

A function that takes a JSX element and returns a response. By default, it uses the @vercel/og image renderer to render the JSX into a PNG image. The renderer should respect the aspectRatio option if it is provided.

See the custom images worker example for an example of how to specify a custom renderer.

imagesRoute - Options

The imagesRoute refers to the return value of createImagesWorker and is a Next.js API route handler.

jsxToResponse

  • Type: (jsx: ReactElement, options?: { aspectRatio: ImageAspectRatio }) => Promise<Response>
  • Default: undefined

A function that takes a JSX element and returns a response. By default, it uses the @vercel/og image renderer to render the JSX into a PNG image. The renderer should respect the aspectRatio option if it is provided.

See the custom images worker example for an example of how to specify a custom renderer.