Skip to content

Generate PDFs in Node.js

Fullbleed's optional Node package renders static HTML/CSS into PDFs using a bundled WebAssembly build of the Rust engine. It includes fonts and runs locally; you do not need Python, Rust, or a browser to use the installed package.

The quickstart and downloadable invoice use Node package 0.9.0, powered by Fullbleed 2.5.46. The integration and core engine have separate versions.

Already have an HTML template? Try the static HTML migration project, including local fonts, a flowing table and an optional Puppeteer reference.

Create your first PDF

With Node.js 22 or newer, install the npm package:

npm install fullbleed

To pin this guide's version, use npm install --save-exact fullbleed@0.9.0. The npm package contains the same verified bytes as the GitHub release.

Save this as invoice.mjs and run node invoice.mjs:

import { writeFile } from 'node:fs/promises';
import { renderPdf } from 'fullbleed';

const result = await renderPdf({
  html: '<h1>Invoice NS-1042</h1><p>Consulting: USD 1,200.00</p>',
  css: '@page { size: A4; margin: 20mm } h1 { color: #175c52 }',
  previewDpi: 96,
});

await writeFile('invoice.pdf', result.pdf);
await writeFile('invoice.png', result.previews[0]);
console.log(`${result.pages} page; engine ${result.engineVersion}`);

Open invoice.pdf or invoice.png. Inter is the default font, and previews come from the finalized PDF. result.pdf is a Node Buffer that you can also return from an HTTP handler or write to your storage.

CommonJS applications can use const { renderPdf } = require('fullbleed'). TypeScript declarations are included for both module styles.

You can also author documents with JavaScript components and JSX and export HTML with or without styles.

For rendering inside a web page, use the browser entry and starter. For Cloudflare Workers, use the Workers adapter and invoice endpoint introduced in package 0.8.0 and included in the same 0.9.0 package.

For many records sharing one design, generate a combined PDF batch. That guide uses package 0.9.0 and covers variable page counts and per-record reports.

Export a design from the playground

Open the playground, edit an example or open your own HTML, CSS, images, and fonts. Choose Node.js under Project language, then select Download project. The ZIP contains your current source, selected assets, bundled fonts and licenses, a locked npm dependency, and render.mjs. Extract it and run:

npm ci --ignore-scripts
npm run render

Open output/document.pdf and the previews in output/preview/. Edit input.html or style.css and run the renderer again. These playground exports use Node package 0.9.5 with the same 2.5.51 engine. Their renderer sets defaultStyles: false to preserve font inheritance and CSS layers exactly as entered in the playground.

Start with a designed invoice

Northstar Studio invoice generated by the Node package, with cream paper, serif typography, a green total panel, and orange accents.

Download the Node invoice project Open its generated PDF

Extract the project and run these commands in its directory:

npm ci --ignore-scripts
npm run render

Open output/invoice/invoice.pdf and output/invoice/page-1.png. Edit the customer value in render.mjs or change the HTML/CSS. The script escapes the customer name before inserting it into the document. All example data is fictional. The lockfile pins the npm package version and its integrity hash.

The layout uses the bundled Inter, DM Serif Display, and Bebas Neue families.

Style a report with gradients

Report page with serif headings, large summary figures, gradient chart bars, and a numbered footer.

The same project ZIP includes the three-page Common Ground report. After extracting the project and running npm ci --ignore-scripts, render it with:

npm run render:report

Open output/report/report.pdf and output/report/page-2.png. Edit report.html and report.css to adapt its layout and fictional data. The chart uses CSS linear-gradient(180deg, #d9bc77, #a9b884); the image above is a native preview of the finalized PDF. Fullbleed 2.5.5 fixes gradient fills that were missing from these PNG previews in earlier releases.

Open the report PDF Explore its HTML and CSS

Bring fonts and image assets

Use the actual family name for normal/italic CSS selection, or a PostScript name for an explicit face. Review appearance and line breaks when upgrading; the font-family guide explains font selection.

Pass additional font bytes through fonts, and use their actual family names in CSS. Pass images through assets, mapping relative names to Buffer or Uint8Array values. For example, an asset named brand/logo.svg is available as assets/brand/logo.svg in your HTML.

The engine uses an in-memory filesystem for the supplied inputs and does not fetch remote URLs. Data URIs also work for document images. The package API reference includes a complete font and asset example.

With package 0.8.5 or newer, you can preserve the filename used by a CSS @font-face rule. Supply the font as { name, data }:

import { readFile } from 'node:fs/promises';
import { renderPdf } from 'fullbleed';

const result = await renderPdf({
  html: '<p class="brand">Your document, your typography.</p>',
  css: '@font-face { font-family: Brand; src: url("Brand.ttf"); } .brand { font-family: Brand; }',
  fonts: [{ name: 'Brand.ttf', data: await readFile('Brand.ttf') }],
  defaultStyles: false,
});

Use a .ttf or .otf filename without folders. Filenames must be unique; existing font-byte inputs remain supported. Playground exports preserve these names automatically.

Fonts in page headers and footers

Use Node package 0.9.1 or newer (engine 2.5.48) when a page header or footer uses a custom @font-face alias such as Brand:

npm install --save-exact fullbleed@0.9.1

Register the named font bytes as above, then use font-family: Brand in a margin box or in @page. To share the font with the document, set it on html and use defaultStyles: false. Page typography inherits from html through @page to each margin box; a family set only on body does not set the page font. The font registration guide shows the CSS and explains fallback families and weight selection.

The 0.9.1 release retains the font comparisons. The invoice and report downloads above keep their tested 0.9.0 dependency pins and use explicit family names.

Unembedded PDF Standard 14 faces now have bundled substitutes for native PNG previews. The PDF keeps its original font resources, text, and advances; a PDF reader can use a different substitute design. Register your chosen font when the exact branded appearance matters. See the preview comparison and font limits.

Use it in an application

For a working web-app integration, use the Next.js PDF download starter. It includes an App Router handler, designed invoice, bundled-asset configuration and an isolated check of the production standalone server.

By default, rendering runs in a worker, with separate document state for concurrent calls. The promise waits for its worker to exit, including after failure, timeout, or cancellation. Sequential await renderPdf() calls therefore do not overlap worker lifetimes. A timeout or abort starts termination; the promise settles after the worker stops.

Use timeoutMs, maxPages, and an AbortSignal to bound a job. Limit concurrent calls to fit your server's memory; each worker's WebAssembly memory ceiling is 512 MiB. Preview images can use more memory than PDF-only rendering.

Node package 0.4.0 adds a shared render queue with active and waiting limits, deadlines that include queue time, cancellation, and shutdown. The guide includes a runnable six-invoice batch. Use one queue per application process to share the limits across request handlers.

Rendering errors reject with a FullbleedError and a code such as INVALID_INPUT, MISSING_GLYPHS, PAGE_LIMIT, TIMEOUT, or ABORTED. Invalid font data is rejected. Use registered font families: unavailable CSS families can fall back, and the engine's glyph report does not establish visual correctness. Review the final PDF and previews when adapting a design.

Contain render-process failures

On a Node host that permits child processes, use isolation: 'process' to run each request's engine and worker in a fresh process:

const result = await renderPdf({
  html: '<h1>Monthly statement</h1>',
  isolation: 'process',
  timeoutMs: 10_000,
  maxPages: 20,
});

The caller does not compile WebAssembly or create render workers in this mode. The promise waits for process exit and IPC disconnection before settling, even after success. A failed child exit rejects with PROCESS_FAILED; available exitCode and signal fields describe the exit. Timeouts and aborts terminate the child before rejecting. A PDF received before a failed shutdown is not returned as a successful result.

Process startup adds latency and memory use. There is no process pool or automatic retry; keep concurrency bounded. Application startup flags and NODE_OPTIONS are not replayed in the child. This option requires a normal Node executable and is not an operating-system security sandbox. See the process isolation guide for deployment details and the tested failure paths. The Next.js starter uses this mode for its PDF route.

An intermittent process crash on Linux with Node 24.21.0 was observed with fullbleed@0.1.2; issue #7 remains open. Version 0.1.3 fixes worker shutdown timing, but has not established that this native crash is resolved. See the runtime investigation for the observed scope and synthetic diagnostic. A process crash can occur before JavaScript can return an error in worker mode. Process isolation contains tested child failures; it does not establish a fix for that native crash.

This first Node API covers ordinary PDF rendering and previews. Use the Python API or Rust crate for profiles, template overlays, and compiled variable-data workflows. Unknown Node options are rejected. For JavaScript execution or live website behavior, use a browser.

Verification and source

The package checks real document output, failure recovery, ESM/CommonJS, and TypeScript. Its release evidence compares retained native and WebAssembly fixtures and installs the same tarball across Node 22, 24, and 26 on Windows, Linux, and macOS. These are scoped engineering checks, not PDF standards certification.

Version 0.8.7 fixes radial gradients that change color or opacity at the final stop. Earlier long-code wrapping and pre-line whitespace fixes remain included, with explicit no-wrap controls preserved. See the preformatted-text checks for the tested cases.

The 0.9.0 release verification retains native/Wasm comparisons, installed-package queue and recovery checks, and browser downloads in Chrome, Firefox and Playwright WebKit. Its pagination checks use independent PDF readers to check row preservation, repeated table headings, page bounds and footnote placement, with the previous release as a failing control.

The invoice and report on this page were rendered with package 0.8.7 / engine 2.5.43. The download manifest records the public package integrity and exact PDF/preview hashes. The downloadable projects and this guide's runnable snippets are checked against the installed public package; see the current guide verification.

Package source and API · npm package · Versioned release and evidence · CSS coverage · Examples

Ask a question or share a document in GitHub Discussions.