fastify-xpdf

PDF generation and manipulation for Fastify 5. Uses Puppeteer (Chrome headless) for HTML/Markdown/URL rendering and pdf-lib for form filling, merging, page extraction, and metadata — with optional per-call upload to S3-compatible storage via @xenterprises/fastify-xstorage.

Breaking change (1.0): the decorator was renamed from fastify.xPDF to fastify.xPdf (lowercase df). Update every call site. The plugin-level useStorage option was also removed — saving to storage is now gated per call via saveToStorage: true, and passing it without xStorage registered throws an error instead of silently skipping the upload.

Installation

npm install @xenterprises/fastify-xpdf

# Optional — required only when calling methods with saveToStorage: true
npm install @xenterprises/fastify-xstorage

Quick Start

import Fastify from "fastify";
import xPDF from "@xenterprises/fastify-xpdf";

const fastify = Fastify();

await fastify.register(xPDF, {
  format: "A4",
  printBackground: true,
  margin: { top: "1cm", right: "1cm", bottom: "1cm", left: "1cm" },
});

fastify.get("/reports/:id/pdf", async (request, reply) => {
  const html = await renderReportHtml(request.params.id);
  const { buffer } = await fastify.xPdf.generateFromHtml(html);
  return reply
    .header("Content-Type", "application/pdf")
    .header("Content-Disposition", 'attachment; filename="report.pdf"')
    .send(buffer);
});

await fastify.listen({ port: 3000 });

All options have defaults — await fastify.register(xPDF) is a valid minimal registration.

Options

Methods

All methods are on fastify.xPdf.

Generation (Puppeteer-based):

• generateFromHtml(html, options?) — Convert an HTML string to PDF.
• generateFromMarkdown(markdown, options?) — Convert a Markdown string to PDF.
• generateFromUrl(url, options?) — Render a live URL to PDF with Puppeteer.

Form operations (pdf-lib):

• fillForm(pdfBuffer, fieldValues, options?) — Fill and optionally flatten PDF form fields.
• listFormFields(pdfBuffer) — Enumerate all form fields in a PDF template.

Manipulation (pdf-lib):

• mergePDFs(pdfBuffers, options?) — Merge multiple PDFs into a single document.
• extractPages(pdfBuffer, pageIndices, options?) — Extract specific pages into a new document.
• getPageCount / getMetadata — Get page count or full metadata (title, author, dates, size).

Exported Helpers

Available via import { helpers } from "@xenterprises/fastify-xpdf/helpers":

Error Reference

Registration fails fast on invalid option types. Messages name the plugin, the option, and an example:

Method calls throw real Error objects prefixed with [xPDF]:

Storage upload failures (when xStorage is registered) propagate the original xStorage error to the caller; they are logged message-only and never swallowed.

Environment Variables

None. The plugin never reads process.env — every option is passed explicitly via app.register(xPDF, { ... }). If you want environment-driven configuration, read the variables in your own app and pass the values in:

await fastify.register(xPDF, {
  format: process.env.PDF_FORMAT ?? "A4",
  headless: process.env.PUPPETEER_HEADLESS !== "false",
});

How It Works

The plugin uses two engines. Puppeteer handles HTML, Markdown, and URL-to-PDF generation: a single Chrome browser instance is lazily initialised on the first generation call (via the injectable browserFactory option), reused across requests, and closed via Fastify's onClose hook on shutdown. It auto-reconnects if the browser disconnects. pdf-lib handles all manipulation operations (form filling, merging, page extraction, metadata) in pure JavaScript with no browser. When @xenterprises/fastify-xstorage is registered on the same Fastify instance, any method result can be uploaded to S3-compatible storage by passing saveToStorage: true on that call (with an optional folder override); the response then includes storageKey and url. There is no plugin-level storage toggle — passing saveToStorage: true without xStorage registered throws an actionable error. The plugin decorates Fastify with fastify.xPdf and registers itself as xpdf via fastify-plugin with a fastify: "5.x" constraint.

AI Context

package: "@xenterprises/fastify-xpdf"
type: fastify-plugin
use-when: PDF generation from HTML/Markdown/URL via Puppeteer; PDF manipulation (form fill, merge, extract pages, metadata) via pdf-lib
decorator: fastify.xPdf (generateFromHtml, generateFromMarkdown, generateFromUrl, fillForm, listFormFields, mergePDFs, extractPages, getPageCount, getMetadata)
env: none — plugin never reads process.env; all configuration via register options
helper-exports: "@xenterprises/fastify-xpdf/helpers" (generatePdfFilename, isValidPdfBuffer, sanitizeFilename, wrapHtmlTemplate, parseMargin, etc.)
optional-integration: fastify-xstorage — register first, then pass saveToStorage: true per call; throws if xStorage is missing