Introduction

Takumi is one layout engine, with text and inline layout ported from Chromium. It turns JSX, HTML, and CSS into images, PDFs, and other outputs without a headless browser.

Pick a packageCopy Anchor Link

Each package runs the same layout engine. Pick the one that produces your output.

The rest of this page uses takumi-js.

For how a render goes from input to output, and where it differs from a browser, see How Takumi works.

InstallCopy Anchor Link

npm i takumi-js

takumi-js ships two backends and picks one at runtime. You install nothing else.

Use WebAssembly in Node.jsCopy Anchor Link

Set the takumi-wasm export condition to render on WebAssembly in Node.js and Bun too. Use it when the native addon cannot ship with your server, such as a serverless function bundled into one file. Without a bundler, pass the condition to Node.js:

node --conditions=takumi-wasm server.js

When Vite bundles your server, add the condition to its server conditions and bundle Takumi into the server build:

import { defaultServerConditions, defineConfig } from "vite";

export default defineConfig({
  ssr: {
    noExternal: ["takumi-js", "@takumi-rs/wasm", "@takumi-rs/helpers"],
    resolve: { conditions: ["takumi-wasm", ...defaultServerConditions] },
  },
  build: { ssrEmitAssets: true },
});

ssrEmitAssets writes the WebAssembly binary next to the server bundle, where Takumi reads it at runtime. Without it, the binary goes only to the client build. Takumi then also looks in a client directory next to the server output, and fails with Unable to locate Takumi WASM asset for SSR if the binary is not there either.

With esbuild, add module after takumi-wasm, and copy the binary with the file loader:

import { build } from "esbuild";

await build({
  entryPoints: ["src/server.ts"],
  bundle: true,
  platform: "node",
  format: "esm",
  outdir: "dist",
  conditions: ["takumi-wasm", "module"],
  loader: { ".wasm": "file" },
});

Custom conditions replace the module condition esbuild sets by default. Without module, the bundle keeps a loader that reads the binary from node_modules and fails with ENOENT once it runs from dist.

render and ImageResponse load the binary on their first call. To create a Renderer from takumi-js/wasm yourself, await ready() first:

import { ready, Renderer } from "takumi-js/wasm";

await ready();

const renderer = new Renderer();

ready() loads the binary the export conditions pick, on every runtime. Only the first call loads it, and later calls wait for that load. A failed load is retried on the next call.

Render an imageCopy Anchor Link

render takes JSX and returns encoded image bytes. Save this as image.tsx and run bun image.tsx. In Node.js, compile the JSX first.

import { render } from "takumi-js";
import { writeFile } from "node:fs/promises";

const png = await render(
  <div
    style={{
      fontSize: 72,
      background: "linear-gradient(to bottom right, #fff7ed, #fecaca)",
    }}
    tw="w-full h-full flex items-center justify-center"
  >
    Hello Takumi
  </div>,
  { width: 1200, height: 630 }, 
);

await writeFile("hello.png", png);

• width and height set the image size. Leave one out to size that side to the content.
• tw="w-full h-full" makes the root fill the image.

Serve it over HTTPCopy Anchor Link

ImageResponse extends the web Response. Return it from any route handler that uses Request and Response. Its API matches next/og.

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

export function GET() {
  return new ImageResponse(<div tw="w-full h-full grid place-items-center">Hello Takumi</div>, {
    width: 1200,
    height: 630,
  });
}

Load a fontCopy Anchor Link

googleFonts loads Google Fonts families in one request. A weight range or an axes entry loads the variable font. Then font-weight and font-variation-settings set its axes per element.

import { render } from "takumi-js";
import { googleFonts } from "takumi-js/helpers";

const png = await render(
  <div
    style={{
      fontSize: 72,
      fontFamily: "Fraunces",
      fontVariationSettings: "'opsz' 72, 'wght' 700",
    }}
    tw="w-full h-full flex items-center justify-center"
  >
    Hello Takumi
  </div>,
  {
    width: 1200,
    height: 630,
    fonts: googleFonts([
      {
        name: "Fraunces",
        weight: "100..900",
        axes: { opsz: "9..144" },
      },
    ]),
  },
);

fonts also takes a font URL, raw bytes, or a descriptor. To load fonts before the first request, register them on a Renderer.

Coming from satoriCopy Anchor Link

A bare <div> lays out as a block, as in a browser. Keep explicit Flexbox styles when you move a Satori template, and compare the output. renderSvg() returns SVG like satori() does. render() returns encoded image bytes. See the Satori comparison and migration guide.

Next stepsCopy Anchor Link