Introduction

Takumi generates Open Graph (OG) images, social cards, and banners from JSX, HTML, or node trees. Style them with CSS or Tailwind, then render PNG, JPEG, WebP, SVG, or animations without a headless browser.

Use takumi-js for image output. For invoices, reports, and other documents, start with PDF generation.

Install

npm i takumi-js

takumi-js bundles both bindings: the native renderer (@takumi-rs/core) and the WebAssembly one (@takumi-rs/wasm). It picks the right one at runtime: native on Node.js, WebAssembly on Cloudflare Workers, Vercel Edge, Deno, and the browser. No extra install.

Render an image

render takes JSX and returns image bytes. The built-in font covers the Latin text in this example. Save it as image.tsx and run bun image.tsx, or compile the JSX before running it in Node.js.

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 canvas.
• tw="w-full h-full" makes the root fill that canvas.

Serve it over HTTP

ImageResponse extends the web Response, so any runtime with Request and Response can return it. The 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 font

googleFonts fetches families in one request and returns fonts entries. A weight range or an axes entry loads the variable font, so font-weight and font-variation-settings drive 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 raw bytes, a descriptor, or a bare URL string.
• Rendering many images? Register the fonts once on a Renderer and reuse it.

Coming from satori

Takumi defaults a bare <div> to block layout. Keep explicit Flexbox styles when migrating a Satori template, and compare the rendered output. renderSvg() returns SVG, while render() returns encoded image bytes. See the Satori comparison and migration guide.

Next steps