Invoice
Thanks for your order.
\");\n```\n\nPass embedded fonts (via `loadFont`) and a `resolveImage` callback for production output:\n\n```ts\nimport { readFile } from \"node:fs/promises\";\nimport { PDFDocument } from \"pdf-lib\";\nimport { loadFont, loadImage } from \"@boxpdf/writer\";\nimport { htmlToPdf } from \"@boxpdf/html-reader\";\n\nconst pdf = await PDFDocument.create();\nconst inter = await loadFont(pdf, await readFile(\"Inter-Regular.ttf\"));\nconst interBold = await loadFont(pdf, await readFile(\"Inter-Bold.ttf\"));\nconst logo = await loadImage(pdf, await readFile(\"logo.png\"));\n\nconst bytes = await htmlToPdf(await readFile(\"invoice.html\", \"utf8\"), {\n pdf, // reuse the document you embedded into\n font: inter,\n boldFont: interBold,\n resolveImage: ({ url }) => (url === \"logo.png\" ? logo : undefined),\n margin: 40\n});\n```\n\nOptions: `font` / `boldFont` / `italicFont` / `boldItalicFont` (default to Helvetica), `pdf` (render into an existing document), `margin` (default 40), `size` (default US Letter), `width` (CSS containing-block width; defaults to the page's content width), `debug`, plus everything `htmlToBoxpdf` accepts (`resolveFont`, `resolveImage`, `baseUrl`, `defaultFontSize`, `defaultColor`, `diagnostics`, `profile`).\n\n### `htmlToBoxpdf` — the nodes, for full control\n\n`htmlToBoxpdf` turns HTML into normal boxpdf nodes without rendering. Reach for it when you need the nodes themselves, the `warnings`/`diagnostics`, multiple render passes, or `renderFlow` headers/footers.\n\n```ts\nimport { readFile } from \"node:fs/promises\";\nimport { PDFDocument } from \"pdf-lib\";\nimport { loadFont, loadImage, renderFlow } from \"@boxpdf/writer\";\nimport { fontFamily, htmlToBoxpdf } from \"@boxpdf/html-reader\";\n\nconst html = await readFile(\"invoice.html\", \"utf8\");\nconst pdf = await PDFDocument.create();\n\nconst inter = await loadFont(pdf, await readFile(\"Inter-Regular.ttf\"));\nconst interBold = await loadFont(pdf, await readFile(\"Inter-Bold.ttf\"));\nconst logo = await loadImage(pdf, await readFile(\"logo.png\"));\n\nconst result = htmlToBoxpdf(html, {\n font: inter,\n boldFont: interBold,\n resolveFont: fontFamily({\n Inter: { normal: inter, bold: interBold },\n \"sans-serif\": { normal: inter, bold: interBold }\n }),\n resolveImage: ({ url }) => (url === \"logo.png\" ? logo : undefined),\n baseUrl: process.cwd(),\n width: 532\n});\n\nconsole.log(result.warnings);\nawait renderFlow(pdf, result.nodes, { margin: 40 });\nconst bytes = await pdf.save();\n```\n\n`width` is the CSS containing block width in PDF points. A US Letter page with 40pt margins has a 532pt content width, so `width: 532` is a good default.\n\n### `streamHtmlToPdf` — bounded large-document conversion\n\n`streamHtmlToPdf` accepts a function that reopens the HTML for each of its two\npasses and writes PDF bytes incrementally. Embed fonts before calling it; use\n`prepare` to embed images found by the resource preflight before output begins.\n\n```ts\nimport { createReadStream, createWriteStream } from \"node:fs\";\nimport { PDFDocument, StandardFonts } from \"pdf-lib\";\nimport { nodeAdapter } from \"@boxpdf/writer\";\nimport { streamHtmlToPdf } from \"@boxpdf/html-reader\";\n\nconst pdf = await PDFDocument.create();\nconst font = await pdf.embedFont(StandardFonts.Helvetica);\n\nconst result = await streamHtmlToPdf(\n () => createReadStream(\"archive.html\"),\n nodeAdapter(createWriteStream(\"archive.pdf\")),\n { pdf, font, width: 532, margin: 40 }\n);\n\nconsole.log(result.pageCount, result.dom.maxBufferedNodes);\n```\n\nOrdinary block wrappers and tables are released in bounded continuation\nfragments. Atomic layouts such as flex/grid, positioned or transformed\ncontainers, and single uninterrupted text nodes have explicit safety caps and\nfail with a useful error when they cannot be streamed safely. Selectors whose\nmeaning depends on sibling position conservatively disable wrapper\nfragmentation.\n\n## Fonts\n\nFonts are explicit. `boxpdf-html` does not discover system fonts and does not ship a browser font stack. This keeps rendering deterministic and works in serverless runtimes.\n\nAt minimum, pass `font`. Pass `boldFont` and `italicFont` if your HTML uses bold or italic text:\n\n```ts\nconst result = htmlToBoxpdf(html, {\n font,\n boldFont,\n italicFont,\n width: 532\n});\n```\n\nFor CSS `font-family`, use `fontFamily()`:\n\n```ts\nconst resolveFont = fontFamily({\n Inter: {\n normal: interRegular,\n bold: interBold,\n italic: interItalic,\n boldItalic: interBoldItalic\n },\n Helvetica: {\n normal: fallback,\n bold: fallbackBold\n },\n \"sans-serif\": {\n normal: fallback,\n bold: fallbackBold\n }\n});\n```\n\nThe resolver receives `{ families, weight, style }` and returns a pdf-lib `PDFFont`. You can provide your own resolver when you need looser mapping, font aliases, language-specific fallbacks, or weight synthesis.\n\nGotchas:\n\n- `font-family: system-ui` only works if your resolver maps `system-ui`.\n- Standard pdf-lib fonts are convenient but limited; use embedded TTF/OTF fonts for real documents.\n- Complex shaping depends on pdf-lib/fontkit behavior. Western-language invoice/report text is the target.\n- Font metrics affect layout. Use the same embedded fonts in tests and production when visual stability matters.\n\n## Tailwind CSS\n\nTailwind works when you render its generated CSS, not raw class names alone. The usual flow is:\n\n1. Write document HTML with Tailwind classes.\n2. Run Tailwind against that HTML.\n3. Inline or pass the generated CSS to `boxpdf-html`.\n4. Render with a containing width that matches your intended PDF content area.\n\nExample source:\n\n```html\n\n
\n```\n\nBuild CSS:\n\n```css\n@import \"tailwindcss\";\n@source \"./invoice.html\";\n```\n\n```sh\nnpx tailwindcss -i ./tailwind-input.css -o ./tailwind-output.css --minify\nnpx @boxpdf/html-reader invoice.html invoice.pdf --css ./tailwind-output.css\n```\n\nSupported Tailwind patterns include common spacing, color, text, border, radius, width/height, flex, grid, table, image, and arbitrary-value utilities. Unsupported utility declarations can be reported with `--unsupported-css` or `diagnostics: { unsupportedCss: true }`.\n\nTailwind gotchas:\n\n- Responsive/state variants are parsed as CSS; there is no viewport interaction. Choose a single generated CSS target for the PDF you want.\n- Two-dimensional transforms support ordered `translate`, `scale`, `rotate`, `skew`, and `matrix` function lists, their X/Y variants, `transform-origin`, and the standalone `translate`, `rotate`, and `scale` properties. Length/percentage translations and `deg`, `grad`, `rad`, and `turn` angles are supported. Three-dimensional transforms, shadows, filters, transitions, and browser-only effects are ignored or reported as unsupported.\n- Tailwind preflight resets are mostly harmless. Diagnostics intentionally focus on utility selectors instead of noisy base selectors.\n- If text layout matters, use the same fonts in Tailwind design review and PDF rendering.\n\n## Images\n\nThe API uses `resolveImage` because pdf-lib images must be embedded before rendering:\n\n```ts\nconst images = new Map([\n [\"logo.png\", await loadImage(pdf, await readFile(\"logo.png\"))]\n]);\n\nhtmlToBoxpdf(html, {\n font,\n resolveImage: ({ url }) => images.get(url),\n baseUrl: process.cwd()\n});\n```\n\nThe CLI preloads local, `http(s)`, and `data:` image URLs referenced by `\n
\n\n
\n \n
\n Status
\nPaid
\n\n
\n Notes
\nTwo fraction column wraps later.
\n