boxpdf
Open-source HTML-to-PDF for JavaScript runtimes
boxpdf is a tiny OSS toolkit for server-side PDF generation:
render document-style HTML + Tailwind CSS with boxpdf-html,
or build layouts directly with a flexbox-lite DSL over
pdf-lib. Runs in
Node, Cloudflare Workers, Deno,
and the browser. No WASM. No headless browser. No React.
import { cleanTheme, hline, hstack, renderFlow, text, vstack } from "boxpdf";
import { PDFDocument, StandardFonts } from "pdf-lib";
const pdf = await PDFDocument.create();
const font = await pdf.embedFont(StandardFonts.Helvetica);
const bold = await pdf.embedFont(StandardFonts.HelveticaBold);
const theme = cleanTheme(font, bold);
await renderFlow(pdf, [
vstack({ gap: 8 },
text("Receipt #18472", theme.type.h1),
text("May 14, 2026", theme.type.caption)
),
hline(theme.hr),
hstack({ gap: 16 },
text("Wool socks", theme.type.body),
text("$28.00", { ...theme.type.body, font: bold, align: "right", width: 80 })
)
]);
const bytes = await pdf.save(); // -> Uint8ArrayWorks on Cloudflare Workers without nodejs_compat or any WASM flag. Verified end-to-end with embedded Inter.
vstack / hstack with padding, margin, gap, justify, align, grow, shrink. Real word-wrapping and ellipsis.
streamFlow emits bytes to a WritableStream as each page closes. In the 1000-page benchmark it used 25.4 MB peak heap versus 219.6 MB for renderFlow + pdf.save().
Password encryption happens during serialization—including streamed output—with optional owner credentials and viewer permissions. No temporary plaintext PDF or encryption post-process.
Drop-in cleanTheme, stripeTheme, editorialTheme, brutalistTheme. Same code restyles every template.
renderFlow paginates with atomic children. keepTogether bundles widows. Page headers and footers with { pageNumber, totalPages } built in.
Optional boxpdf/inter ships subsetted Inter (82 KB / weight). loadFont(pdf, source) and the boxpdf font add CLI bundle any TTF as base64.
link({ href }, ...), underline, strikethrough, title / author / subject as renderFlow options.
renderFlow(pdf, nodes, { debug: true }) outlines every content and margin box in red and orange. Trace layouts visually.
Core is <7 KB minified. boxpdf/inter and @pdf-lib/fontkit only load when you use them.
boxpdf-html is the open-source HTML renderer for boxpdf. It turns document-style HTML and generated Tailwind CSS into boxpdf primitives, so you can ship PDF output without a browser runtime.
<div class="p-6 bg-[#f8fafc] text-gray-900">
<div class="max-w-[520px] rounded-[10px] border bg-white p-5 shadow-sm">
<div class="grid grid-cols-[1fr_2fr] gap-x-4 gap-y-3">
<div class="rounded-md border border-blue-200 bg-blue-50 p-3">
<p class="text-xs font-semibold uppercase tracking-wide text-blue-700">Status</p>
<p class="mt-1 text-sm font-bold">Paid</p>
</div>
<div class="rounded-md border border-gray-200 p-3">
<p class="text-xs font-semibold uppercase tracking-wide text-gray-600">Notes</p>
<p class="mt-1 text-sm leading-5">Two fraction column wraps later.</p>
</div>
</div>
<div class="mt-4 flex items-center justify-between rounded-md bg-gray-900 px-4 py-3 text-white">
<span class="text-sm font-semibold">Amount due</span>
<span class="text-xl font-bold leading-none">$1,250.00</span>
</div>
</div>
</div>
Bounded-memory HTML streaming
The HTML CLI makes two bounded passes: one to discover CSS, fonts, and images, then one to parse, lay out, and write the PDF incrementally. A single open wrapper can span every fragment, so large real-world documents do not need artificial page-sized roots.
npx boxpdf-html archive.html archive.pdf --stream
cat archive.html | npx boxpdf-html - archive.pdf --streamThe destination is replaced only after conversion succeeds. Stdin is spooled to a temporary file for the required second pass.
The visual test suite raster-compares every streamed page against buffered output. Inspect the benchmark and visual-parity evidence.
Same layout code, four aesthetics. Swap the theme and every template restyles.
Production-ready documents in templates/. Copy a file, edit it for your data, ship it.
npm install boxpdf pdf-lib
pdf-lib is a peer dependency. If you want custom-font embedding (incl. boxpdf/inter), @pdf-lib/fontkit comes along for the ride and is lazy-loaded only when you embed a non-standard font.
Both the core and the boxpdf/inter subpath are verified to run on Cloudflare Workers without nodejs_compat or any WASM flag. Drop it into a worker handler:
import { Hono } from "hono";
import { PDFDocument, StandardFonts } from "pdf-lib";
import { cleanTheme, renderFlow, text, vstack } from "boxpdf";
const app = new Hono();
app.get("/receipt.pdf", async (c) => {
const pdf = await PDFDocument.create();
const font = await pdf.embedFont(StandardFonts.Helvetica);
const bold = await pdf.embedFont(StandardFonts.HelveticaBold);
const t = cleanTheme(font, bold);
await renderFlow(pdf, [
text("Thanks!", t.type.h1),
text("This PDF was generated at the edge.", t.type.body)
]);
const bytes = await pdf.save();
return new Response(bytes, { headers: { "content-type": "application/pdf" } });
});
export default app;| boxpdf | pdf-lib | @react-pdf/renderer | jsPDF | |
|---|---|---|---|---|
| Declarative layout | ✓ | ✗ | ✓ (JSX) | ✗ |
| Cloudflare Workers | ✓ | ✓ | ✗ (fontkit WASM) | partial |
| Streaming output | ✓ streamFlow (Web Writable, bounded memory) | ✗ | Node only | ✗ |
| Custom fonts | ✓ via fontkit (lazy) | ✓ via fontkit | ✓ | limited |
| Core bundle | ~7 KB gz | ~250 KB gz | ~250 KB gz | ~80 KB gz |
| JSX runtime conflict | none | n/a | requires React | n/a |
Sizes are approximate. Measure yourself.
Peak heap during render. 50 lines of text per page. Each measurement runs in its own subprocess. @react-pdf/renderer uses Standard Helvetica (no font embedding) to match the boxpdf paths.
| Pages | streamFlow | renderFlow | @react-pdf/renderer | Output |
|---|---|---|---|---|
| 50 | 12.8 MB | 31.7 MB | 160.8 MB | 70 KB |
| 250 | 15.4 MB | 91.1 MB | 643.1 MB | 347 KB |
| 500 | 18.7 MB | 120.8 MB | 1,219.9 MB | 693 KB |
| 1000 | 25.4 MB | 219.6 MB | 2,292.6 MB | 1.4 MB |
Bench source: scripts/bench-memory.ts. Design doc: docs/design/streaming.md.
Encryption built into the writer
boxpdf writes PDF 2.0 Standard Security Handler documents with AES-256. Strings, content streams, fonts, and images are encrypted as objects are serialized, preserving bounded document memory.
await streamFlow(pdf, writable, rows(), {
encryption: {
password: process.env.PDF_PASSWORD,
permissions: { copying: false }
}
});The same encryption option works with savePdf, flowToPdf, and renderToPdf.
export BOXPDF_PASSWORD="open me"
npx boxpdf-html archive.html archive.pdf --stream --password-env BOXPDF_PASSWORDThe CLI reads the password from the named environment variable. Owner passwords and viewer permissions are available through the library API. Viewer permissions are advisory, as defined by the PDF standard.
Security design and scope: docs/design/encryption.md.
loadFont (URL, bytes, base64, data URL), embedInter, loadImage helpersboxpdf font add CLI bundles any TTF as base64 bytes for loadFontembedInter(pdf, { tabularFigures: true }))table() primitive with styled cells, colSpan, valign, border collapse, and repeated headerssvgPath(), imageFit(), aspectRatio(), debug overlay, formatCurrency, defineStyleszIndexstreamFlow, with bounded-document-memory validation.