Package Exports

html-pdf-puppeteer
html-pdf-puppeteer/lib/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (html-pdf-puppeteer) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

html-pdf-puppeteer

HTML to PDF converter using Puppeteer and headless Chrome - a modern replacement for the deprecated node-html-pdf

Why this library?

The original node-html-pdf library relied on PhantomJS, which has been deprecated for years. This library provides a drop-in replacement with the same API, but uses modern headless Chrome via Puppeteer instead.

Features

✅ Same API as node-html-pdf for easy migration
✅ Uses modern Puppeteer and headless Chrome
✅ Support for complex CSS and modern web standards
✅ Headers and footers support
✅ Custom page sizes and orientations
✅ Async/await and callback support
✅ Generate PDFs from HTML strings, files, or URLs
✅ Output to file, buffer, or stream
✅ TypeScript definitions included

Installation

npm install html-pdf-puppeteer

Or install globally for CLI usage:

npm install -g html-pdf-puppeteer

Quick Start

const fs = require('fs');
const pdf = require('html-pdf-puppeteer');
const html = fs.readFileSync('./input.html', 'utf8');

const options = { format: 'Letter' };

pdf.create(html, options).toFile('./output.pdf', function(err, res) {
  if (err) return console.log(err);
  console.log(res); // { filename: '/path/to/output.pdf' }
});

📄 Example PDFs

See real-world output examples from this library:

Basic Example (30KB) - Simple HTML to PDF conversion
Header & Footer Example (48KB) - Professional document with headers/footers
Invoice Example (100KB) - Complex invoice with tables and styling
Annual Report Example (534KB) - Multi-page report with images, tables, charts, and custom headers/footers

All example source code is available in the examples/ directory.

API

pdf.create(html, [options])

Creates a new PDF document instance.

Parameters:

html (string): HTML content as a string
options (object, optional): Configuration options

Returns: PDFDocument instance

Methods

.toFile([filepath,] callback)

Generates PDF and saves to a file.

pdf.create(html, options).toFile('./output.pdf', function(err, res) {
  console.log(res.filename);
});

.toBuffer(callback)

Generates PDF and returns as a Buffer.

pdf.create(html).toBuffer(function(err, buffer){
  console.log('PDF buffer:', buffer);
});

.toStream(callback)

Generates PDF and returns as a Stream.

pdf.create(html).toStream(function(err, stream){
  stream.pipe(fs.createWriteStream('./output.pdf'));
});

Async/Await Support

All methods return promises and support async/await:

async function generatePDF() {
  const buffer = await pdf.create(html, options).toBuffer();
  const result = await pdf.create(html, options).toFile('./output.pdf');
}

Options

const options = {
  // Export options
  directory: "/tmp",       // Output directory (default: '/tmp')

  // Page size - use either format OR width/height
  format: "Letter",        // A3, A4, A5, Legal, Letter, Tabloid
  width: "8in",           // Custom width (units: mm, cm, in, px)
  height: "10.5in",       // Custom height (units: mm, cm, in, px)
  
  orientation: "portrait", // portrait or landscape

  // Margins
  border: "0",            // default is 0, units: mm, cm, in, px
  // OR
  border: {
    top: "2in",
    right: "1in",
    bottom: "2in",
    left: "1.5in"
  },

  // Header and footer
  header: {
    height: "45mm",
    contents: '<div style="text-align: center;">Header Content</div>'
  },
  footer: {
    height: "28mm",
    contents: '<div>Page <span class="pageNumber"></span> of <span class="totalPages"></span></div>'
  },

  // Rendering options
  base: "file:///path/to/assets/", // Base path for loading files
  printBackground: true,            // Print background graphics (default: true)
  preferCSSPageSize: false,         // Use CSS-defined page size
  
  // Timing
  timeout: 30000,          // Timeout in milliseconds (default: 30000)
  renderDelay: 1000,       // Wait time before rendering (milliseconds)
  // OR
  renderDelay: "manual",   // Wait for custom event (see below)

  // HTTP options
  httpHeaders: {
    "Authorization": "Bearer TOKEN"
  },
  httpCookies: [
    {
      name: "session",
      value: "abc123",
      domain: "localhost",
      path: "/",
      httponly: true,
      secure: false
    }
  ],

  // Puppeteer options
  puppeteerArgs: ['--no-sandbox', '--disable-setuid-sandbox'],
  headless: true,          // Run in headless mode (default: true)
  
  // Zoom
  zoomFactor: 1            // Page zoom factor (default: 1)
};

Examples

Basic PDF Generation

const pdf = require('html-pdf-puppeteer');

const html = '<h1>Hello World</h1>';
const options = { format: 'A4' };

pdf.create(html, options).toFile('./output.pdf', (err, res) => {
  if (err) return console.error(err);
  console.log('PDF created:', res.filename);
});

With CSS Styling

const html = `
<!DOCTYPE html>
<html>
<head>
  <style>
    body { font-family: Arial; margin: 40px; }
    h1 { color: #333; }
    .box { background: #f0f0f0; padding: 20px; }
  </style>
</head>
<body>
  <h1>Styled Document</h1>
  <div class="box">This is a styled box</div>
</body>
</html>
`;

pdf.create(html, { format: 'Letter' }).toFile('./styled.pdf');

Headers and Footers

const options = {
  format: 'A4',
  border: { top: '20mm', bottom: '20mm' },
  header: {
    height: '15mm',
    contents: '<div style="text-align:center;">My Header</div>'
  },
  footer: {
    height: '15mm',
    contents: '<div style="text-align:center;">Page <span class="pageNumber"></span></div>'
  }
};

pdf.create(html, options).toFile('./with-headers.pdf');

Manual Render Timing

For dynamically loaded content:

const html = `
<html>
<body>
  <div id="content">Loading...</div>
  <script>
    setTimeout(() => {
      document.getElementById('content').innerHTML = 'Loaded!';
      document.dispatchEvent(new Event('pdf-render-ready'));
    }, 2000);
  </script>
</body>
</html>
`;

const options = { renderDelay: 'manual' };
pdf.create(html, options).toFile('./dynamic.pdf');

Using Streams

pdf.create(html).toStream((err, stream) => {
  if (err) return console.error(err);
  stream.pipe(fs.createWriteStream('./output.pdf'));
});

Async/Await

async function generateReport() {
  try {
    const result = await pdf.create(html, options).toFile('./report.pdf');
    console.log('Report generated:', result.filename);
  } catch (error) {
    console.error('Error:', error);
  }
}

Command Line Usage

# Basic usage
html-pdf-puppeteer input.html output.pdf

# With options
html-pdf-puppeteer input.html output.pdf --format A4 --orientation landscape

Migration from node-html-pdf

This library is designed as a drop-in replacement. In most cases, you can simply:

Replace require('html-pdf') with require('html-pdf-puppeteer')
Update your package.json dependencies

Note: Some PhantomJS-specific options are not supported. See the options table above for supported options.

Differences from node-html-pdf

Uses Puppeteer/Chrome instead of PhantomJS
Better CSS3 and modern web standards support
No phantomPath or phantomArgs options (use puppeteerArgs instead)
Slightly different header/footer implementation
Better performance and reliability

Requirements

Node.js >= 14.0.0
Puppeteer will download Chromium automatically on install (~170MB)

TypeScript

TypeScript definitions are included:

import * as pdf from 'html-pdf-puppeteer';

const html: string = '<h1>Hello</h1>';
const options: pdf.CreateOptions = { format: 'A4' };

pdf.create(html, options).toFile('./output.pdf');

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License

Acknowledgments

Inspired by node-html-pdf by Marc Bachmann
Built with Puppeteer

Support

If you encounter any issues or have questions, please open an issue on GitHub.