@boxpdf/writer

A box-layout DSL over pdf-lib. Implemented in portable JavaScript, it runs in Node 20+, Cloudflare Workers, Deno, and browsers.

Live gallery: https://earonesty.github.io/boxpdf/

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

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

flowToPdf owns the document lifecycle and returns the saved 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/writer";

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();

Install

npm install @boxpdf/writer pdf-lib

pdf-lib is a peer dependency.

Legacy package name

The original boxpdf package remains supported and is published from the same build at the same version. Existing imports and the boxpdf CLI continue to work unchanged:

npm install boxpdf pdf-lib

New projects should use @boxpdf/writer. Both package names expose the same API, and both provide the boxpdf command.

What it does

• Declarative layout primitives: vstack, hstack, text, image, hline, vline, spacer, flex, keepTogether, link, svgPath, table.
• Layout-aware AcroForm fields: text, checkbox, radio, dropdown, option-list, and push-button widgets.
• 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.

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:

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

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

claude mcp add boxpdf -- npx -y boxpdf mcp

Themes

import { cleanTheme, editorialTheme, standardFonts } from "@boxpdf/writer";

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:

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? }.

AcroForm fields

Form widgets are atomic layout nodes, so they work inside stacks, tables, pagination, and streamed documents without manual page coordinates.

import {
  checkbox,
  dropdown,
  flowToPdf,
  standardFonts,
  text,
  textField,
  vstack
} from "@boxpdf/writer";

const bytes = await flowToPdf(async (pdf) => {
  const { font } = await standardFonts(pdf);
  return [
    vstack({ gap: 10 },
      text("Registration", { size: 18, font }),
      textField({
        name: "person.name",
        width: 260,
        height: 26,
        font,
        fontSize: 11,
        required: true
      }),
      dropdown({
        name: "person.state",
        width: 140,
        height: 26,
        font,
        options: ["CA", "NY", "WA"]
      }),
      checkbox({
        name: "terms.accepted",
        width: 16,
        height: 16,
        required: true
      })
    )
  ];
});