HTML to PDF Converter with Puppeteer

Common errors

• Error: Cannot find module 'pdf-creator-node'

  cause The package is not installed or incorrectly referenced.
  fix Run `npm install pdf-creator-node` or `yarn add pdf-creator-node`.

• Error: Node.js 18 or newer is required.

  cause Running the package with an unsupported Node.js version.
  fix Upgrade your Node.js environment to version 18 or higher.

• Error: Failed to launch the browser process! The browser should be installed via 'npm install'

  cause Puppeteer failed to find or launch Chromium, likely due to a failed download or permissions issue during installation, or `PUPPETEER_SKIP_DOWNLOAD` being set without a pre-installed browser.
  fix Ensure `puppeteer` can download Chromium by checking network access during `npm install`. If `PUPPETEER_SKIP_DOWNLOAD` is set, ensure Chromium is installed and `PUPPETEER_EXECUTABLE_PATH` points to it. Check file permissions for the `node_modules` directory.

• TypeError: pdf.create is not a function

  cause Incorrect import or require statement, or accessing an uninitialized module. Possibly trying to destructure `pdf` from a `require` call that returns the default export.
  fix For CommonJS, use `const pdf = require('pdf-creator-node');`. For ESM (TypeScript/modern Node.js), use `import pdf from 'pdf-creator-node';` and ensure your environment supports ESM.

Warnings

• breaking Version 4.0.0 replaced PhantomJS with Puppeteer (headless Chromium) for rendering. This results in a larger installation size (hundreds of MB for Chromium download) and potential differences in PDF layout and styling compared to previous versions. Deprecated options like `phantomPath` are now ignored.
  Fix: Review PDF output for layout changes. Account for increased install size, especially in CI/CD environments (consider `PUPPETEER_CACHE_DIR` or `PUPPETEER_SKIP_DOWNLOAD`). Remove PhantomJS-specific options from `PdfCreateOptions`.
• breaking The `footer.contents` option for `PdfCreateOptions` has changed behavior in v4.0.0. Only one template (`default`, `first`, or `last`) is applied; per-page numeric keys (e.g., for page 2) are no longer supported.
  Fix: Consolidate footer content into a single `default`, `first`, or `last` template. Use `{{page}}` and `{{pages}}` placeholders within that single template for page numbering.
• gotcha Puppeteer, and by extension `pdf-creator-node` (v4+), downloads a Chromium browser instance upon installation. This can significantly increase `node_modules` size and installation time, particularly in resource-constrained environments or CI/CD pipelines.
  Fix: For CI/CD, consider setting `PUPPETEER_SKIP_DOWNLOAD=true` if Chromium is pre-installed or `PUPPETEER_CACHE_DIR` to cache the downloaded browser across builds. Be aware of the memory and CPU footprint when running many concurrent PDF generation tasks.
• gotcha The minimum Node.js version required is 18. Using older Node.js versions will lead to compatibility issues and errors.
  Fix: Ensure your project's Node.js environment is version 18 or newer.

Install

• npm install pdf-creator-node npm
• yarn add pdf-creator-node yarn
• pnpm add pdf-creator-node pnpm

Imports

• pdf
  wrong:

  const pdf = require('pdf-creator-node');

  correct:

  import pdf from 'pdf-creator-node';

  While CommonJS `require` works, TypeScript users should prefer ESM `import` for better type inference and modern module practices. `pdf` is the default export.
• PdfDocument

  import type { PdfDocument } from 'pdf-creator-node';

  Used for type-checking the document object structure. Important for TypeScript projects.
• PdfCreateOptions

  import type { PdfCreateOptions } from 'pdf-creator-node';

  Used for type-checking the PDF creation options. Essential for robust TypeScript usage.

Quickstart

This quickstart demonstrates how to create a PDF from an HTML and Handlebars template, including dynamic data, custom headers, and footers, saving it to a file, using ESM syntax.

import pdf from "pdf-creator-node";
import fs from "fs";
import path from "path";

const htmlTemplate = `
  <!DOCTYPE html>
  <html>
    <head>
      <style>
        body { font-family: sans-serif; margin: 20mm; }
        h1 { color: #333; }
        table { width: 100%; border-collapse: collapse; margin-top: 20px; }
        th, td { border: 1px solid #ddd; padding: 8px; text-align: left; }
        .footer { position: fixed; bottom: 0; width: 100%; text-align: center; font-size: 10px; color: #666; }
      </style>
    </head>
    <body>
      <h1>User Report</h1>
      <table>
        <thead>
          <tr>
            <th>Name</th>
            <th>Age</th>
          </tr>
        </thead>
        <tbody>
          {{#each users}}
          <tr>
            <td>{{this.name}}</td>
            <td>{{this.age}}</td>
          </tr>
          {{/each}}
        </tbody>
      </table>
      <div class="footer">Page {{page}} of {{pages}}</div>
    </body>
  </html>
`;

const usersData = [
  { name: "Alice", age: 30 },
  { name: "Bob", age: 24 },
  { name: "Charlie", age: 35 }
];

const options = {
  format: "A4",
  orientation: "portrait",
  border: "10mm",
  header: { height: "15mm", contents: { default: '<h2 style="text-align: center;">PDF Report Header</h2>' } },
  footer: { height: "10mm", contents: { default: '<span style="color: #444;">{{page}}</span>/<span>{{pages}}</span>' } },
  path: path.join(process.cwd(), 'output.pdf') // Use path.join for cross-platform compatibility
};

const document = {
  html: htmlTemplate,
  data: { users: usersData },
  path: options.path,
};

pdf.create(document, options)
  .then((res) => console.log('PDF created:', res.filename))
  .catch((err) => console.error('Error creating PDF:', err));