X Enterprises
fastify-xpdf

generateFromHtml

Convert an HTML string to PDF using Puppeteer (Chrome headless).

generateFromHtml

Convert an HTML string to a PDF buffer using a Puppeteer-managed Chrome headless browser. Supports page format, orientation, margins, headers/footers, and optional upload to xStorage.

Signature

fastify.xPDF.generateFromHtml(
  html: string,
  options?: HtmlPdfOptions,
): Promise<PdfResult>

interface HtmlPdfOptions {
  filename?: string
  format?: string            // "A4", "Letter", "A3", "A5", "Tabloid", etc.
  landscape?: boolean
  margin?: { top?: string; right?: string; bottom?: string; left?: string }
  printBackground?: boolean
  displayHeaderFooter?: boolean
  headerTemplate?: string    // HTML string for header
  footerTemplate?: string    // HTML string for footer
  saveToStorage?: boolean    // upload via xStorage
  folder?: string            // storage folder override
}

interface PdfResult {
  buffer: Buffer
  filename: string
  size: number               // bytes
  storageKey?: string        // present if saveToStorage: true
  url?: string               // present if saveToStorage: true
}

Params

NameTypeRequiredDescription
htmlstringYesHTML content to render — must be a non-empty string
options.filenamestringNoOutput filename (auto-generated with timestamp if omitted)
options.formatstringNoPage format override (defaults to plugin format option)
options.landscapebooleanNoLandscape orientation
options.marginobjectNoPage margins override (CSS units, e.g. "1cm")
options.printBackgroundbooleanNoBackground colours/images (defaults to plugin setting)
options.displayHeaderFooterbooleanNoEnable header/footer
options.headerTemplatestringNoHTML for the page header
options.footerTemplatestringNoHTML for the page footer
options.saveToStoragebooleanNoUpload result buffer to xStorage
options.folderstringNoStorage folder (defaults to plugin defaultFolder)

Returns

PdfResult — always includes buffer, filename, and size. Includes storageKey and url when saveToStorage: true and xStorage is registered.

Throws

ErrorWhen
[xPDF] HTML content must be a non-empty stringhtml is empty, null, or not a string
[xPDF] Failed to initialize PDF browserPuppeteer/Chrome launch failure

Examples

Generate and stream a PDF response

fastify.get("/invoices/:id/pdf", async (request, reply) => {
  const invoice = await fastify.prisma.invoice.findUnique({
    where: { id: request.params.id },
  });

  const html = `
    <!DOCTYPE html>
    <html>
      <head><style>body { font-family: sans-serif; padding: 2cm; }</style></head>
      <body>
        <h1>Invoice #${invoice.number}</h1>
        <p>Due: ${invoice.dueDate}</p>
        <p>Total: $${invoice.total}</p>
      </body>
    </html>
  `;

  const { buffer, filename } = await fastify.xPDF.generateFromHtml(html, {
    format: "Letter",
    filename: `invoice-${invoice.number}.pdf`,
  });

  return reply
    .header("Content-Type", "application/pdf")
    .header("Content-Disposition", `attachment; filename="${filename}"`)
    .send(buffer);
});

Generate with header/footer and save to storage

const { url } = await fastify.xPDF.generateFromHtml(reportHtml, {
  format: "A4",
  landscape: true,
  displayHeaderFooter: true,
  headerTemplate: `<div style="font-size:10px;text-align:right;width:100%;padding-right:1cm;">
    <span class="date"></span>
  </div>`,
  footerTemplate: `<div style="font-size:10px;text-align:center;width:100%;">
    Page <span class="pageNumber"></span> of <span class="totalPages"></span>
  </div>`,
  saveToStorage: true,
  folder: "reports/2025",
});

console.log(url); // public CDN URL of the uploaded PDF

See Also

AI Context

package: "@xenterprises/fastify-xpdf"
method: fastify.xPDF.generateFromHtml(html, options?)
use-when: Convert an HTML string to PDF using Puppeteer (Chrome headless)
params: html (string), options (format, margin, printBackground, saveToStorage, filename, folder)
returns: { buffer, size } | { buffer, size, storageKey, url } (when saveToStorage: true)

fillForm

Fill PDF form fields (text, checkbox, radio, dropdown) using pdf-lib and optionally flatten the result.

generateFromMarkdown

Convert a Markdown string to PDF — parsed with marked and rendered via Puppeteer.

Copyright © 2026