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. To turn an HTML file into a PDF without writing code, use the command line instead.

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

¹ Size keywords ignore case.

² A side left out of the object is "auto".

³ Without backgroundColor, viewers show the page as white.

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({ cache }) sets the byte budget of each cache the renderer keeps, including the fonts that renders' fonts lists load. See Caching.

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.