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 automatic upload to S3-compatible storage via @xenterprises/fastify-xstorage.

Installation

npm install @xenterprises/fastify-xpdf

# Optional — required only if useStorage: 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 });

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

All errors use the [xPDF] prefix.

Environment Variables

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, 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 useStorage: true and @xenterprises/fastify-xstorage is registered on the same Fastify instance, any method accepting saveToStorage: true will upload the result buffer to S3-compatible storage and include storageKey and url in the response. The plugin decorates Fastify with fastify.xPDF with a fastify >= 5.0.0 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: PUPPETEER_HEADLESS, PUPPETEER_ARGS, PDF_DEFAULT_FORMAT, PDF_USE_STORAGE, PDF_DEFAULT_FOLDER (all optional)
helper-exports: "@xenterprises/fastify-xpdf/helpers" (generatePdfFilename, isValidPdfBuffer, sanitizeFilename, wrapHtmlTemplate, parseMargin, etc.)
optional-integration: fastify-xstorage — register first if useStorage: true