Generate PDFs

takumi-pdf is takumi's PDF output, for invoices, reports, and other paged documents. It shares one layout engine, a port of Chromium's layout, with image output and the paint tree. A template lays out the same way in each.

Pass JSX, an HTML string, or a node tree, and style it with CSS or Tailwind. The renderer runs in WebAssembly and does not launch a browser.

npm i takumi-pdf @takumi-rs/helpers

Render a documentCopy Anchor Link

Save this as invoice.tsx and run bun invoice.tsx to write invoice.pdf. On Node.js, compile the JSX first.

import { render } from "takumi-pdf";
import { PageNumber, TotalPages } from "takumi-pdf/primitives";
import { googleFonts } from "@takumi-rs/helpers";
import { writeFile } from "node:fs/promises";

const pdf = await render(
  <main>
    <h1>Invoice 1042</h1>
    <p>Total: $1,290</p>
  </main>,
  {
    size: "a4",
    fonts: await googleFonts(["Inter"]),
    footer: (
      <div tw="flex w-full justify-center text-[10px] text-gray-500">
        Page <PageNumber /> of <TotalPages />
      </div>
    ),
  },
);

await writeFile("invoice.pdf", pdf);

render() returns a Uint8Array. By default:

• Content flows across A4 pages with automatic margins.
• Text stays selectable, and fonts are embedded as subsets.
• Text inside an SVG image is drawn as outlines, so it cannot be selected.

An HTML string goes through the same parser as takumi-js. A <style> tag in the string applies only to that render:

import { render } from "takumi-pdf";

const pdf = await render(`
  <style>.total { font-weight: 700 }</style>
  <div><span class="total">Total: $1,290</span></div>
`);

Headers, footers, and measure() take the same inputs.

Page setupCopy Anchor Link

import { render } from "takumi-pdf";

const pdf = await render(report, {
  size: "letter", // a page keyword, or { width, height } in CSS px at 96 dpi
  landscape: true,
  margin: { top: 48, right: 32, bottom: 48, left: 32 },
});

Set page geometry with these options. CSS @page rules are not parsed.

Each keyword is a portrait paper size:

Automatic marginsCopy Anchor Link

On a page one inch or smaller along an axis, automatic margins on that axis are 0. To set a numeric margin that fits a band, see Sizing the margin.

Reuse a rendererCopy Anchor Link

render() and measure() share one renderer. Create a PdfRenderer to keep a separate font registry:

import { PdfRenderer } from "takumi-pdf";

const renderer = new PdfRenderer();
await renderer.registerFont("https://example.com/fonts/Inter-Regular.woff2");

const pdf = await renderer.render(doc);

Replace the example URL with your font file. A font loads once, however many renders list it.

new PdfRenderer({ fontCacheMaxBytes }) caps the decoded fonts that renders' fonts lists keep. Past the cap, the least recently used families are released and load again when a render lists them. Fonts from registerFont() are never released.

RuntimesCopy Anchor Link

Use the default import on Node.js, Bun, and Cloudflare Workers. For manual initialization, import takumi-pdf/no-init.

Next.jsCopy Anchor Link

Import takumi-pdf/next in a Next.js route handler. It works on the Node and Edge runtimes without a serverExternalPackages entry.

import { render } from "takumi-pdf/next";

In the browserCopy Anchor Link

In a browser bundle, initialize the renderer with takumi-pdf/no-init and takumi-pdf/wasm-url:

import init, { render } from "takumi-pdf/no-init";
import wasmUrl from "takumi-pdf/wasm-url";

await init({ module_or_path: wasmUrl });

takumi-pdf/wasm-url resolves the binary with new URL(specifier, import.meta.url). Vite, webpack, and Turbopack rewrite that call to the asset they emit. The module has no top-level await, so it also works in a worker bundled as an IIFE.

Keep the default entry in server code. A Vite SSR build leaves the URL pointing at the server chunk, where the asset is not emitted.

On Turbopack, remove any turbopack.rules entry that maps *.wasm to type: "wasm". That rule makes Turbopack instantiate the binary and look for wasm-bindgen glue the package does not ship.

Choose the next guideCopy Anchor Link

For complete document patterns, see Invoices, Reports, and Charts.