ImageResponse

Return an ImageResponse from a route handler to serve a rendered image. It extends the web Response, so it works in any runtime with Request and Response. Its API matches next/og.

import { ImageResponse } from "takumi-js/response";

export function GET() {
  return new ImageResponse(<div>Hello Takumi</div>, { width: 1200, height: 630 });
}

The first argument takes what render() takes: JSX, an HTML string, or a node tree.

OptionsCopy Anchor Link

ImageResponseOptions is the render() options plus the ResponseInit fields and an error hook.

Custom headersCopy Anchor Link

content-type follows format unless you set it. Takumi sets no other headers. This handler lets browsers and shared caches reuse the image for one hour:

import { ImageResponse } from "takumi-js/response";

export function GET() {
  return new ImageResponse(<div>Hello Takumi</div>, {
    width: 1200,
    height: 630,
    format: "webp",
    headers: {
      "Cache-Control": "public, max-age=3600",
    },
  });
}

Match max-age to how often the content changes.

Error handlingCopy Anchor Link

The response streams its body while the render runs, so the status is already set when a render fails. To send a fallback instead, await ready. It resolves when the render succeeds and rejects when it fails.

import { ImageResponse } from "takumi-js/response";

export async function GET() {
  const response = new ImageResponse(<div>Hello Takumi</div>, { width: 1200, height: 630 });

  try {
    await response.ready; 
    return response;
  } catch {
    return new Response("Failed to generate image", { status: 500 });
  }
}

onError is for side effects such as logging. Takumi ignores its return value, and the response stream still errors. Use ready to send a fallback.

import { ImageResponse } from "takumi-js/response";

export function GET() {
  return new ImageResponse(<div>Hello Takumi</div>, {
    width: 1200,
    height: 630,
    onError: (error) => console.error(error), 
  });
}

Bring your own rendererCopy Anchor Link

Without renderer, every response in the process shares one default renderer and its caches. Pass your own Renderer to configure it: set cache budgets, or register fonts up front.

import { Renderer } from "takumi-js/node";
import { ImageResponse } from "takumi-js/response";

const renderer = new Renderer({ cacheMaxBytes: 128 * 1024 * 1024 }); 

export function GET() {
  return new ImageResponse(<div>Hello Takumi</div>, {
    width: 1200,
    height: 630,
    renderer, 
  });
}

takumi-js/node exports the native renderer. On WebAssembly runtimes, use the Renderer from takumi-js/wasm and call its init first, as in the measure() example.