[ogawa0071]

Closes #442

Summary

Adds void/og: an ImageResponse that takes the same arguments as next/og and renders JSX or an HTML string to a PNG from a route handler, on Cloudflare Workers and on the Node.js, Bun and Deno targets.

// routes/og/[slug].tsx
import { defineHandler } from 'void';
import { ImageResponse } from 'void/og';

export const GET = defineHandler((c) =>
  new ImageResponse(
    <div style={{ display: 'flex', fontSize: 72 }}>Hello {c.req.param('slug')}</div>,
  ),
);

Why Takumi rather than Satori

The current Satori (0.62) fails in workerd: its HarfBuzz Emscripten loader reads self.location.href (TypeError: Cannot read properties of undefined (reading 'href') in Miniflare), so using it would mean rewriting Satori's inlined loader in Void's Vite plugin. Takumi (takumi-js) ships a Wasm build with a workerd export condition, which the Cloudflare Vite plugin loads as a compiled module in dev and builds, plus a native addon for Node.js and Bun. It takes JSX or HTML, so void/og stays a thin wrapper.

What the wrapper adds

• next/og defaults: a 1200 × 630 PNG, Content-Type, and debug. Cache-Control is public, max-age=0, must-revalidate, as in Next.js 16, and no-cache, no-store during local development. The guide shows how to cache image routes with routing.revalidate.
• Fallback fonts: Takumi's built-in Geist covers Latin, so for text it cannot draw (Japanese, Chinese, Korean, Thai, Arabic, Cyrillic, symbols and more) the wrapper loads the matching Noto family, or Geist's own Latin Extended and Cyrillic subsets, from Google Fonts, much as @vercel/og does. Han text is drawn as Japanese, as in next/og, unless Hangul or lang says otherwise. Latin text stays on the built-in Geist, and a font that fails to download is left out instead of failing the image.
• Each image renders with only its own fonts (Takumi otherwise uses every font registered in the process), fonts passed as bytes register once, and emoji images are cached per isolate.
• Comments in packages/void/src/runtime/og.ts cite the @vercel/og, Satori and Next.js code each behavior follows.

Node.js, Bun and Deno

Takumi loads its renderer from files next to its own code, which a bundle cannot carry. On these targets the build fails with the install command when the app has no supported takumi-js in its own dependencies; the dev server only warns.

Workers Free

Apps that don't import void/og bundle nothing extra (covered by a test). Takumi's Wasm is about 4 MB (1.7 MB gzipped). Measured on V8 with the Wasm build, a simple card takes around 10 ms of CPU, richer ones 30–80 ms, and the first render in a new isolate more than 100 ms, so the guide tells Workers Free apps to cache image routes with revalidation.

takumi-js version

takumi-js is pinned to ~2.18.2. 2.19.0 loads only the first font whose unicode-range covers a character and draws the whole word as .notdef boxes when that font lacks the glyph: with Japanese in the image, "Łódź" renders as four boxes, and Noto Sans Symbols claims ❤ without having it. 2.16.2, 2.17.1 and 2.18.2 render the same images correctly. packages/void/AGENTS.md notes how to check a fix before raising the range.

Docs

• New guide: docs/guide/og-images.md, including "Coming from next/og" and the Node.js, Bun and Deno setup.
• void/og in the API reference, a link from the head() guide, a note in the Node.js, Bun and Deno integration guide, and a task row in the void skill.

Tests

• packages/void/test/unit/og.test.ts (25 tests): defaults and headers, formats, JSX, fallback-font selection and subsetting, per-image font isolation, emoji, images.throwOnError, and the Node.js build check.
• packages/void/test/integration/og-image.test.ts (6 tests): the dev server in workerd, the built Worker in Miniflare (one CompiledWasm module), an app without React, an app without void/og (no Wasm in its bundle), and the Node.js target, which renders with the app's takumi-js and fails the build without it.
• .github/scripts/packed-consumer.mjs renders an image route from the packed tarballs in dev and preview, and on the Node.js target.

Ran vp run build:all, vp run check, vp run build:docs, the tests above, and the packed-consumer smoke suite (npm and pnpm).

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	takumi-js@​2.18.2

View full report