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.

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.

Coding agentsCopy Anchor Link

Takumi ships skills that teach coding agents its API and rules, and how to migrate from satori or a headless browser. Install them into your project:

npx skills add kane50613/takumi

The docs are also indexed for agents at /llms.txt, and each page is available as Markdown by adding .md to its URL.

Next stepsCopy Anchor Link