ImageResponse

ImageResponse extends the web Response, so any runtime with Request and Response returns it from a route handler. The API matches next/og.

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

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

Options

ImageResponseOptions is RenderOptions plus the standard ResponseInit fields and an error hook.

Custom headers

content-type defaults to the chosen format. Set cache headers or override anything via headers.

new ImageResponse(<OgImage />, {
  format: "webp",
  headers: {
    "Cache-Control": "public, immutable, max-age=31536000",
  },
});

ETag

imageResponse renders the image before it builds the Response, so it can hash the bytes into a strong ETag. Clients revalidate with If-None-Match and skip the download while the image is unchanged.

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

export function GET() {
  return imageResponse(<OgImage />, {
    width: 1200,
    height: 630,
    headers: { "Cache-Control": "public, max-age=0, must-revalidate" },
  });
}

new ImageResponse(...) carries no ETag, because a framework reads its headers while the render is still running. imageResponse takes the same options, but awaits instead: it has no ready promise, the returned promise rejects when the render fails, and onError still runs. An etag of your own in headers is left alone.

Error handling

ImageResponse exposes a ready promise: it resolves when the render succeeds and rejects when it fails. Await it to serve a fallback.

const response = new ImageResponse(<OgImage />);

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

onError is a notification hook for side effects like logging. Its return value is ignored and the response stream still errors, so it cannot substitute a fallback image; use ready for that.

new ImageResponse(<OgImage />, {
  onError: (error) => console.error(error),
});

Bring your own renderer

Pass a renderer to reuse a configured instance across responses. A reused renderer decodes each font and image once.

import { Renderer } from "@takumi-rs/core";

const renderer = new Renderer();

new ImageResponse(<OgImage />, { renderer });