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 },
});

@page CSS rules are not supported. Use these options to set the page geometry.

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.