Generate PDFs

takumi-pdf is takumi's PDF output, for invoices, reports, and other paged documents. 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.

It shares one layout engine, a port of Chromium's layout, with image output and the paint tree. Each output applies the same layout rules to a template.

InstallCopy Anchor Link

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, these hold:

• 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.

Find your guideCopy Anchor Link

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

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.

@page rulesCopy Anchor Link

A @page rule in css or a <style> element sets the page size and margins. It wins over size, landscape, and margin, as CSS does in Chromium with preferCSSPageSize. :first styles the first page, and :left and :right style pages by the side they fall on. The first page is a right page, or a left page when the root element has direction: rtl.

@page {
  size: A5;
  margin: 10mm;
}
@page :first {
  margin-top: 30mm;
}
@page :left {
  margin-left: 25mm;
}
@page :right {
  margin-right: 25mm;
}

• size takes auto, one or two lengths, a keyword from the table above, portrait, or landscape.
• A margin percentage is a share of the page height for the top and bottom margins, and of the page width for the left and right.
• margin: auto is 0, as in Chromium. To leave room for a band, leave that side out of the rule so the "auto" option applies.
• A rule whose margins leave no page area is ignored. A header or footer that leaves no page area fails the render, as it does with the margin option.
• em, rem, and var() read the root element's font size and custom properties. vw and vh read the page the options give, before size changes it.

Margin boxes such as @top-center and other descriptors are not read.

Named pagesCopy Anchor Link

The page property puts an element on a named page, which @page rules with that name style. An element on a different named page than the content before it starts a new page, and its children stay on that page type unless they name their own. Content without a page goes back to the unnamed pages.

@page wide {
  size: A4 landscape;
  margin: 10mm;
}
.wide-table {
  page: wide;
}

@page wide:first styles the first page of the document when it is a wide page, as :first does for unnamed pages. A name without a rule of its own takes the unnamed pages' rules.

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), and 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.

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.