Introduction to takumi-pdf

takumi-pdf renders the same JSX, Tailwind classes, and node trees as image output. It writes a paged vector PDF instead. It ships as a WebAssembly module. It runs on Node.js, Bun, and Cloudflare Workers without Chromium.

• Page breaks honor break-before: page, break-after: page, and break-inside: avoid.
• Headers and footers repeat on every page, with page counters.
• Text stays selectable and searchable. Fonts embed as subsets.
• Links and metadata carry into the output. outline: true builds bookmarks from headings.
• Attachments embed files, including Factur-X e-invoice XML.
• Tagged PDF is on by default. PDF/A-2, A-3, A-4, and PDF/UA-1 pass veraPDF.
• Arabic, bidi text, CJK, Devanagari, and emoji shape correctly.
• Gradients, box-shadow, transforms, and color filters stay vector, conic gradients included.
• 1.5 MB of gzip wasm fits the Cloudflare Workers free plan.

npm i takumi-pdf

Render a document

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

const pdf = await render(<Invoice data={data} />, {
  // A4 portrait with a 48px margin is the default
  size: "a4",
  fonts: await googleFonts(["Inter"]),
  footer: (
    <div tw="flex w-full justify-center text-[10px] text-gray-500">
      Page <span className="pageNumber" /> of <span className="totalPages" />
    </div>
  ),
});

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

render() accepts JSX, HTML strings, or JSON node trees. It returns Uint8Array PDF bytes. Content lays out at the page's content width. It flows onto as many pages as needed.

HTML strings use 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() accept the same inputs.

Page setup

import { render } from "takumi-pdf";

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

These options are the structured form of @page, which takumi does not parse as CSS. size and margin map to the descriptors of the same name, header and footer to its margin boxes.

Leave backgroundColor unset for white paper. A viewer draws white by default, and the file stays free of a full-page rectangle.

Reuse a renderer

render() keeps one shared renderer alive. Construct PdfRenderer directly for applications that manage several font sets:

import { PdfRenderer } from "takumi-pdf";

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

const pdf = await renderer.render(doc);

Registered fonts deduplicate across calls. Rendering many documents pays the font cost once.