@iv-stpn/boxpdf

v1.0.0

Published

8 days ago

Tiny box-layout DSL over pdf-lib. Flexbox-lite for server-side PDF generation in any JS runtime (Node, Cloudflare Workers, Deno, browsers).

0High
0Medium
0Low

iv-stpn

pdf pdf-lib layout flexbox vstack hstack cloudflare-workers edge boxpdf

boxpdf

Forked from earonesty/boxpdf.

A box-layout DSL over pdf-lib. Runs in Node 18+, Cloudflare Workers, Deno, and browsers. No native dependencies, no WASM, no headless browser.

Live gallery: https://iv-stpn.github.io/boxpdf/

import {
  cleanTheme,
  flowToPdf,
  hline,
  hstack,
  standardFonts,
  text,
  vstack,
} from "boxpdf";

const bytes = await flowToPdf(async (pdf) => {
  const { font, bold } = await standardFonts(pdf);
  const theme = cleanTheme({ font, bold });

  return [
    vstack(
      { gap: 8 },
      text("Receipt #18472", theme.type.h1),
      text("May 14, 2026", theme.type.caption),
    ),
    hline(theme.hr),
    hstack(
      { gap: 16, justify: "between", width: 515 },
      text("Wool socks", theme.type.body),
      text("$28.00", {
        ...theme.type.body,
        font: bold,
        align: "right",
        width: 80,
      }),
    ),
  ];
});

No pdf-lib import, no manual PDFDocument.create() / pdf.save() bookkeeping. flowToPdf owns the document lifecycle and returns the bytes; standardFonts embeds the built-in Helvetica family (regular, bold, italic, bold-italic) in one call.

import { PDFDocument, StandardFonts } from "pdf-lib";
import { cleanTheme, renderFlow, text, vstack } from "boxpdf";

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

const bytes = await pdf.save();

renderFlow(pdf, nodes, options) paginates into a document you own and returns { pages } — reach for it when you need multiple render passes, the page objects, or custom save() options. boxpdf also re-exports PDFDocument and StandardFonts, so you never need a direct pdf-lib import.

Install

bun add boxpdf pdf-lib

pdf-lib is a peer dependency.

What it does

Declarative layout primitives: vstack, hstack, text, image, hline, vline, spacer, flex, keepTogether, link, svgPath, table.
Padding, margin, background, background images, borders, borderRadius, overflow clipping, flex-grow, flex-shrink, justify, align.
Rich paragraphs with mixed inline runs, inline replaced nodes, hard breaks, hanging indents, and optional paragraph floats.
Word wrapping with maxLines truncation, optional breakWords, and no-wrap control.
Themes: cleanTheme, stripeTheme, editorialTheme, brutalistTheme.
Multi-page flow with per-page headers and footers, stack fragmentation, and table row fragmentation.
Streaming generation for memory-bounded output.
PDF link annotations, text decorations, document metadata.
~7 KB minified core. Custom fonts pull in @pdf-lib/fontkit only when you call loadFont or embedInter.
WOFF and WOFF2 font formats are auto-decompressed to raw TTF before embedding.
Variable font axis selection (weight, width, slant) for fine-grained face control.
Automatic font caching — duplicate embeddings within the same PDF are deduplicated.

Templates

Files in templates/ cover receipts, boarding passes, resumes, order confirmations, and certificates. Each is a single file.

Scaffold one into your app with the CLI:

bunx boxpdf init receipt --out src/pdf/receipt.ts
bunx boxpdf list

The CLI also ships a resource-only MCP server for agents:

claude mcp add boxpdf -- bunx boxpdf mcp

Themes

import { cleanTheme, editorialTheme, standardFonts } from "boxpdf";

const theme = cleanTheme(await standardFonts(pdf)); // Helvetica
const serif = editorialTheme(await standardFonts(pdf, "times")); // serif + italic slot

Every theme factory accepts either a { font, bold, italic? } object — which is exactly what standardFonts(pdf) and embedInter(pdf) return — or the legacy positional fonts:

cleanTheme({ font, bold }); // or cleanTheme(font, bold)
stripeTheme({ font, bold });
editorialTheme({ font, bold, italic }); // or editorialTheme(font, bold, italic)
brutalistTheme({ font, bold }); // courier regular + bold

standardFonts(pdf, family) takes "helvetica" (default), "times", or "courier" and returns { font, bold, italic, boldItalic }. Every theme exposes the same shape: colors, spacing, radii, type, card, hr.

API

Containers

vstack(style, ...children). Vertical layout.
hstack(style, ...children). Horizontal layout.
keepTogether({ gap?, margin? }, ...children). Paginates atomically.

Container style:

| Field | Type | Notes | | ----------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------- | | width / height | number | Fixed dimensions; otherwise size to content. | | padding / margin | number | { top, right, bottom, left } | Shorthand or per-side. | | background | RGB | Solid fill. | | backgroundImage | { image, width, height, offsetX?, offsetY?, repeat? } | Image painted behind children and clipped to the box. | | border | { color, width } | 1pt+ stroke around the box. | | borderSides | { top?, right?, bottom?, left? } | Per-side strokes using { color, width }. | | borderRadius | number | Corner radius. | | overflow | "visible" | "hidden" | Clips stack children and absolute descendants to the box rectangle. | | position | "relative" | "absolute" | CSS-like positioning for boxes. | | top / right / bottom / left | number | Absolute offsets in points. | | zIndex | number | Paint order for positioned boxes; higher values render later. | | grow | number | Flex grow weight along the parent's main axis. | | shrink | number | Flex shrink weight. | | breakInside | "auto" | "avoid" | Fragmentation hint under renderFlow; avoid keeps the box atomic. | | gap | number | Spacing between children. | | justify | "start" | "center" | "end" | "between" | "around" | "evenly" | Main-axis distribution. | | align | "start" | "center" | "end" | "stretch" | "baseline" | Cross-axis alignment. baseline is intended for hstack rows. |

Leaves

text(content, { size, font, color?, align?, width?, lineHeight?, maxLines?, underline?, strikethrough?, margin? }). Word-wraps when width is set. Truncates with ellipsis when maxLines is set. Default lineHeight uses the font's full height, including descenders.
paragraph({ width?, align?, lineHeight?, margin?, paddingLeft?, textIndent?, wrap?, floats? }, ...runs). Mixed inline text runs and atomic inline nodes that wrap together as one paragraph. Use run(text, style), linkRun(text, style, href), and inlineNode(node, { verticalAlign?, href? }). Newlines in runs create hard breaks; wrap: false disables soft wrapping.
image(pdfImage, { width, height, margin? }). Takes an already-embedded PDFImage.
imageFit(pdfImage, { width, height, fit?, margin? }). Draws an image centered in a fixed rectangle, scaled to contain (default) or cover with clipping.
spacer(size, { grow? }) / flex(weight = 1). Fixed or growing gap.
hline({ color, thickness?, width?, margin? }).
vline({ color, thickness?, height?, margin? }).
link({ href }, child). Wraps a child and registers a PDF Link annotation over its rendered bounding box.
table({ columns, rows, ... }). Fixed / auto / fractional columns with header/footer rows, dividers, styled cells, and row-level page fragmentation under renderFlow. Cells can be plain nodes or { content, colSpan?, padding?, background?, border?, borderSides?, borderRadius?, align?, valign? }.

Rendering

flowToPdf(build, options?). The shortest path to bytes. Creates a PDFDocument, hands it to your build(pdf) callback (embed fonts/images there and return the top-level nodes), paginates with renderFlow, and returns the saved Uint8Array. Same options as renderFlow.
renderFlow(pdf, nodes[], options). Paginates a sequence of top-level children. Top-level vstack nodes may fragment between children; table() fragments between rows and repeats headers on continuation pages. Use keepTogether() or breakInside: "avoid" for atomic blocks. Options: size, margin, header?, footer?, reserveBottom?, title?, author?, subject?, keywords?, creator?, producer?, debug?, warnings?, profile?. Headers and footers receive { pageNumber, totalPages }. Defaults to LETTER (612×792). Pass { size: PageSizes.A4 } for A4. When a top-level child's measured width exceeds the page content area, boxpdf emits a console.warn. Suppress with warnings: false.
streamFlow(pdf, writable, asyncIterable, options). Incremental page-by-page rendering. Memory stays bounded regardless of page count. Writes PDF bytes to a WritableStream<Uint8Array> as each page closes. See the Streaming section below for the contract.
renderToPdf(node, options). One-page convenience.
pageInner(size, margin) / pageContent(size, margin). Compute the inner content width or rectangle of a page.
render(node, page, x, yTop, parentWidth). Draws a subtree at a known position on an existing PDFPage.
measure(node, parentWidth). Intrinsic size without drawing.

Pass { debug: true } to outline content boxes in red and margin boxes in orange.

Helpers

standardFonts(pdf, family?). Embed a built-in pdf-lib family ("helvetica" default, "times", "courier") and get { font, bold, italic, boldItalic } back — ready to drop into any theme. No bytes embedded.
loadFont(pdf, source, options?). Embed a TTF/OTF/WOFF/WOFF2 from URL, bytes, base64, or data URL. Options: { subset, features, weight, width, slant }.
loadImage(pdf, source). Embed a PNG or JPEG (auto-detected).
aspectRatio(ratio, { width }) / aspectRatio(ratio, { height }). Derive the missing dimension for fixed-ratio boxes or images.
formatCurrency(n, { currency, locale }). Intl.NumberFormat wrapper.
defineStyles({ ... }). Typed identity for reusable style bundles.
hex("#1f8a4d") / rgb255(31, 138, 77). Color builders.

Loading fonts

Three options.

Bundled bytes via the CLI. Recommended for production.

bunx boxpdf font add ./Acme-Regular.ttf=regular ./Acme-Bold.ttf=bold \
  --out src/fonts/acme.ts

Generates src/fonts/acme.ts with export const base64 strings. Then:

import { loadFont } from "boxpdf";
import { bold, regular } from "./fonts/acme.js";

const font = await loadFont(pdf, regular);
const acmeBold = await loadFont(pdf, bold);

Bytes ship inside your bundle. No network round-trip.

The built-in Inter weights.

import { loadFont } from "boxpdf";
import { inter, interBold } from "boxpdf/inter";

const font = await loadFont(pdf, inter);
const bold = await loadFont(pdf, interBold);

boxpdf/inter re-exports the same Inter subset as raw base64 strings (inter, interBold, interItalic) and as embedInter(pdf, { italic?, tabularFigures? }). Inter is a variable font — you can also load it with axis values:

const interLight = await loadFont(pdf, inter, { weight: 300 });

Importing boxpdf/inter loads ~325 KB of font bytes plus @pdf-lib/fontkit. The subpath isn't loaded otherwise.

import { embedInter } from "boxpdf/inter";

const { font, bold } = await embedInter(pdf);
const theme = cleanTheme(font, bold);

Pass { tabularFigures: true } to also get tabular-numeral variants for money columns:

const { font, bold, tabularFont, tabularBold } = await embedInter(pdf, {
  tabularFigures: true,
});

text(formatCurrency(amount), { size: 12, font: tabularBold, align: "right" });

Fetch from a URL.

const brand = await loadFont(pdf, "https://example.com/Acme-Regular.ttf");

The full TTF gets fetched and subsetted at embed time. On Cloudflare Workers with a warm cache this is fast (~5-15 ms). On a cold cache or in Node you pay the full fetch each time.

loadFont options

loadFont(pdf, source, options?) accepts { subset?: boolean; features?: Record<string, boolean> } regardless of the source.

| Option | Type | Default | Description | | ---------- | ------------------------- | ------- | ---------------------------------------------------------------------------------------- | | subset | boolean | true | Reduce the font to only the glyphs used in the document. | | features | Record<string, boolean> | {} | OpenType feature toggles. { tnum: true } enables tabular numerals for aligned columns. | | weight | number | — | Variable font weight axis (1–1000). Ignored for non-variable fonts. | | width | number | — | Variable font width axis (0–1000). Ignored for non-variable fonts. | | slant | 0 \| 1 | 0 | Variable font slant/italic axis. 0 = upright, 1 = italic. |

Variable fonts. For fonts with variable axes (e.g., Inter variable, Roboto Flex), pass axis values to select a specific face:

const thickCondensed = await loadFont(pdf, interVariable, {
  weight: 700,
  width: 75,
  slant: 1,
});

WOFF / WOFF2 support. loadFont automatically decompresses WOFF (zlib) and WOFF2 (brotli) files to raw TTF before embedding:

// WOFF
const font = await loadFont(pdf, "https://example.com/font.woff");
// WOFF2
const font2 = await loadFont(pdf, "https://example.com/font.woff2");

WOFF requires zlib.inflateSync; WOFF2 requires brotli.decompress. Both are available in Node and Bun. On edge runtimes, polyfills may be needed.

Font caching. The same font bytes loaded multiple times into the same PDF document are automatically deduplicated — loadFont returns the cached PDFFont object on subsequent calls. Different options (subset, features, axis values) produce separate cache entries so each variant is embedded only once.

const font1 = await loadFont(pdf, inter); // embeds
const font2 = await loadFont(pdf, inter); // returns cached copy
const font3 = await loadFont(pdf, interBold); // embeds (different bytes)
const font4 = await loadFont(pdf, inter, { subset: false }); // embeds (different options)

Streaming output

For long-running document generation, use streamFlow instead of renderFlow. It emits PDF bytes to a WritableStream<Uint8Array> as each page closes. Peak heap is bounded at O(shared resources + one page in flight) regardless of total page count.

import { PDFDocument, StandardFonts } from "pdf-lib";
import { cleanTheme, streamFlow, text } from "boxpdf";

const pdf = await PDFDocument.create();
const font = await pdf.embedFont(StandardFonts.Helvetica);
const bold = await pdf.embedFont(StandardFonts.HelveticaBold);

const { readable, writable } = new TransformStream<Uint8Array, Uint8Array>();
streamFlow(pdf, writable, generate(font, bold)).catch(console.error);

return new Response(readable, {
  headers: { "content-type": "application/pdf" },
});

async function* generate(font, bold) {
  for await (const order of fetchOrders()) {
    yield buildOrderRow(font, bold, order);
  }
}

For Node, adapt a stream.Writable:

import { createWriteStream } from "node:fs";
import { nodeAdapter, streamFlow } from "boxpdf";

const out = nodeAdapter(createWriteStream("./report.pdf"));
await streamFlow(pdf, out, nodes);

Contract

All embedFont / embedJpg / embedPng calls must complete before streamFlow. Embedding mid-stream throws.
The iterable is consumed one node at a time. Pass a generator.
streamFlow closes the writable on success and aborts it on failure. Don't write to it concurrently.
ctx.totalPages is not available in headers and footers. Accessing it throws. Use renderFlow if you need "Page X of Y".
Output is 0-5% larger than renderFlow's default save().

Memory bench

Peak heap during render. Each measurement runs in its own subprocess. 50 lines of text per page. @react-pdf/renderer included for shape comparison.

| Pages | streamFlow peak | renderFlow peak | @react-pdf peak | 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 |

streamFlow holds peak heap roughly flat (12 → 25 MB across a 100× workload increase). renderFlow scales roughly linearly with page count. @react-pdf/renderer adds ~2.3 MB per page in this workload and peaks at 2.3 GB by 1000 pages. See docs/design/streaming.md for the design and the chart.

Cloudflare Workers

Both the core and the boxpdf/inter subpath run on Workers without nodejs_compat.

import { Hono } from "hono";
import { cleanTheme, flowToPdf, standardFonts, text } from "boxpdf";

const app = new Hono();

app.get("/receipt.pdf", async (c) => {
  const bytes = await flowToPdf(async (pdf) => {
    const t = cleanTheme(await standardFonts(pdf));
    return [
      text("Thanks!", t.type.h1),
      text("This PDF was generated at the edge.", t.type.body),
    ];
  });
  return new Response(bytes, {
    headers: { "content-type": "application/pdf" },
  });
});

export default app;

Examples

Runnable scripts in examples/:

receipt.ts. Single-page receipt with totals.
itinerary.ts. Two-band travel itinerary.
invoice.ts. Multi-page invoice with running header and footer plus keepTogether.
debug.ts. Layout with { debug: true }.
themes-showcase.ts. The same receipt rendered in all four themes.
inter-showcase.ts. Clean theme rendered with Inter.
flex-shrink.ts. Three URL-overflow behaviors side by side.
hanging-indent.ts. Paragraph paddingLeft plus negative textIndent for list markers.
overflow-clipping.ts. Clipped cards with absolute overlays and background images.

Flex-shrink

Opt-in via shrink: number on any child of an hstack or vstack. When the sum of children's intrinsic main-axis sizes exceeds the parent's available space, items with shrink > 0 give up shares proportional to shrink × baseSize. Items with shrink = 0 (the default) are frozen.

hstack(
  { width: 360, gap: 16 },
  text("Customer:", { size: 11, font: bold }),
  text("Mr. Algernon Hephaestus Constantine Pemberton-Smythe III", {
    size: 11,
    font,
    shrink: 1,
  }),
);

Behavior:

A text child won't shrink below the width of its widest whitespace-separated word. Wrapping breaks on whitespace, not mid-word.
A single-token string (URL, hash, slug) won't shrink at all and overflows its slot visibly. Two opt-ins lower the floor:
- maxLines: N. The engine ellipsizes overflow. The text shrinks to its slot and trims with ….
- breakWords: true. CSS overflow-wrap: break-word. Hard-breaks at character boundaries.
When shrunk text rewraps to more lines, the container's intrinsic height grows accordingly.
When one item hits its min-word floor, its remaining shrink weight redistributes to siblings.
Works on vstack too when the parent has a fixed height smaller than the sum of children.
link forwards its child's shrink weight, so linked text shrinks and re-wraps like bare text.

See examples/flex-shrink.ts.

Absolute positioning

Boxes can use a small CSS-like positioning model:

vstack(
  { width: 240, height: 120, position: "relative", padding: 16 },
  text("Receipt", { size: 18, font: bold }),
  hstack(
    { position: "absolute", top: 12, right: 12, width: 70 },
    text("PAID", { size: 14, font: bold, align: "center", width: 70 }),
  ),
);