ImageResponse

Generate Open Graph images in HTTP route handlers with the next/og-compatible ImageResponse API.

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

app/og/route.tsx

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

export function () {
  return new (<>Hello Takumi</>, { : 1200, : 630 });
}

Options

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

Prop

Type

Description

widthnumber

Canvas width in pixels.

heightnumber

Canvas height in pixels.

format?"png" | "jpeg" | "webp" | "ico" | "raw"

Output encoder. Sets the default content-type.

quality?number

Encoder quality, 0–100. Applies to JPEG and lossy WebP.

fonts?Font[]

Per-response fonts; identical fonts are decoded once.

images?ImageLoader[]

Pre-fetched images keyed by src.

renderer?Renderer

Bring your own renderer instance to reuse caches.

jsx?FromJsxOptions

JSX conversion options, e.g. { defaultStyles: false }.

headers?HeadersInit

Response headers. content-type defaults to format.

status?number

Response status code.

onError?(error: unknown) => void | Promise<void>

Runs after a render failure, for side effects like logging.

Custom headers

content-type defaults to the chosen format. This handler lets browsers and shared caches reuse the image for one hour. Adjust Cache-Control to match how often the content changes.

Cache an image response

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

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

Error handling

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

Return a fallback response

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

export async function () {
  const  = new (<>Hello Takumi</>, { : 1200, : 630 });

  try {
    await .; 
    return ;
  } catch {
    return new ("Failed to generate image", { : 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.

Log a render failure

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

export function () {
  return new (<>Hello Takumi</>, {
    : 1200,
    : 630,
    : () => .(), 
  });
}

Bring your own renderer

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

Reuse a native renderer

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

const  = new (); 

export function () {
  return new (<>Hello Takumi</>, {
    : 1200,
    : 630,
    , 
  });
}

ImageResponse

Options

Custom headers

Error handling

Bring your own renderer

On this page