HTML-PDF vs PDFKit vs Puppeteer: Architecture and Use Cases Compared

Generating PDFs in Node.js is a common requirement for reports, invoices, and tickets. While html-pdf, pdfkit, and puppeteer all produce PDF files, they work in fundamentally different ways. Understanding their core mechanisms helps you avoid technical debt and performance issues.

🏗️ Core Mechanism: Rendering vs Drawing

html-pdf converts HTML strings into PDFs using PhantomJS.

• It treats the input as a web page.
• The engine renders the HTML silently and captures the output.
• This approach is legacy and relies on deprecated technology.

// html-pdf: Legacy HTML rendering
const pdf = require('html-pdf');
const html = '<h1>Invoice</h1><p>Total: $100</p>';

pdf.create(html).toFile('./invoice.pdf', (err, res) => {
  if (err) return console.error(err);
  console.log('File saved');
});

pdfkit draws PDF elements using vector commands.

• You define coordinates, lines, and text positions manually.
• There is no HTML or CSS parsing involved.
• This gives you full control over the layout logic.

// pdfkit: Vector drawing
const PDFDocument = require('pdfkit');
const doc = new PDFDocument();
const fs = require('fs');

doc.pipe(fs.createWriteStream('./invoice.pdf'));
doc.fontSize(20).text('Invoice', 100, 100);
doc.fontSize(12).text('Total: $100', 100, 130);
doc.end();

puppeteer launches a headless Chrome browser to render content.

• It loads HTML and CSS exactly like a user's browser.
• It supports modern web standards including Flexbox and Grid.
• The page is printed to PDF using the browser's native engine.

// puppeteer: Browser rendering
const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.setContent('<h1>Invoice</h1><p>Total: $100</p>');
  await page.pdf({ path: './invoice.pdf', format: 'A4' });
  await browser.close();
})();

📦 Dependencies and Environment

The tools you need to install and run vary significantly between these packages.

html-pdf requires PhantomJS.

• PhantomJS is a headless WebKit scriptable with a JavaScript API.
• It is no longer developed or supported by its creators.
• Installing it often fails on modern systems due to binary compatibility issues.

// html-pdf: Requires phantomjs binary
// Installation often fails on new OS versions
// npm install html-pdf
// Depends on phantomjs-prebuilt (deprecated)

pdfkit has no external binary dependencies.

• It is pure JavaScript.
• It runs anywhere Node.js runs without extra setup.
• This makes deployment to serverless functions or containers very simple.

// pdfkit: Pure JS
// npm install pdfkit
// No browser or binary needed
// Works in AWS Lambda, Vercel, etc.

puppeteer downloads a Chromium browser instance.

• It bundles a specific version of Chrome to ensure consistency.
• The download size is large (over 100MB).
• Serverless environments need special configuration to run the browser.

// puppeteer: Bundles Chromium
// npm install puppeteer
// Downloads Chrome binary automatically
// Requires system libraries (libgbm, etc.) on Linux

🎨 Styling and Layout Control

How you design the document changes based on the tool you pick.

html-pdf uses CSS for styling.

• You write standard HTML and CSS classes.
• Layout is handled by the rendering engine.
• Support for modern CSS is limited by PhantomJS age.

// html-pdf: CSS styling
const html = `
  <style>.box { color: red; }</style>
  <div class="box">Content</div>
`;
// Limited CSS support due to old WebKit engine

pdfkit uses coordinates and drawing commands.

• You calculate positions for every element.
• There is no cascade or automatic flow.
• You must write logic to handle page breaks manually.

// pdfkit: Coordinate styling
const y = 100;
doc.fillColor('red').text('Content', 50, y);
// Must manually calculate y + height for next element

puppeteer uses full modern CSS.

• You can use external stylesheets or inline styles.
• Layout engines like Flexbox and Grid work as expected.
• Page breaks can be controlled via CSS print media queries.

// puppeteer: Modern CSS
const html = `
  <style>
    .box { color: red; display: flex; }
    @media print { .no-print { display: none; } }
  </style>
  <div class="box">Content</div>
`;
// Full CSS support via Chrome engine

⚠️ Maintenance and Future Proofing

Choosing a library involves considering how long it will remain viable.

html-pdf is deprecated.

• The package has not seen significant updates in years.
• Security vulnerabilities in PhantomJS will not be fixed.
• Using this introduces risk to your production system.

// html-pdf: Deprecated
// Do not use for new projects
// Risk of security issues and build failures

pdfkit is actively maintained.

• It receives updates for bug fixes and features.
• The API is stable and well-documented.
• It is safe for long-term use in production.

// pdfkit: Active
// Stable API
// Safe for production use

puppeteer is actively maintained by Google.

• It tracks Chrome releases closely.
• Security updates are frequent.
• It is the standard for browser automation tasks.

// puppeteer: Active
// Maintained by Chrome team
// Regular security updates

🤝 Similarities: Shared Ground Between Packages

Despite their differences, these libraries share some common goals and patterns.

1. 📄 Output Format is PDF

• All three produce standard PDF files.
• Files can be opened in any PDF reader.
• Suitable for printing or digital distribution.

// All produce .pdf files
// html-pdf -> './file.pdf'
// pdfkit -> './file.pdf'
// puppeteer -> './file.pdf'

2. 💾 Stream Support

• Each package can write to a file stream.
• This allows handling large documents without loading everything into memory.
• Useful for sending files directly to HTTP responses.

// pdfkit: Direct stream
const stream = fs.createWriteStream('file.pdf');
doc.pipe(stream);

// puppeteer: Buffer or path
const pdfBuffer = await page.pdf({ path: 'file.pdf' });

// html-pdf: Callback or stream
pdf.create(html).toStream((err, stream) => { /*...*/ });

3. 🔧 Async Operations

• Generating PDFs is asynchronous in all cases.
• You must handle promises or callbacks.
• Blocking the event loop should be avoided.

// All require async handling
// html-pdf: Callback
// pdfkit: Stream events
// puppeteer: Async/Await

📊 Summary: Key Differences

💡 The Big Picture

html-pdf is a legacy tool — do not use it for new work. It relies on PhantomJS, which is dead technology. If you encounter it in an old codebase, plan to migrate away from it as soon as possible.

pdfkit is like a digital pen 🖊️ — perfect for drawing structured documents from data. Use it for invoices, tickets, or certificates where you control every pixel and do not need HTML layouts.

puppeteer is like a robot browser 🤖 — ideal for converting web pages to PDFs. Use it when you have existing HTML templates or need complex CSS layouts that match your website exactly.

Final Thought: For most modern web applications, puppeteer offers the best balance of fidelity and maintenance. Choose pdfkit only if you need lightweight generation without browser overhead. Avoid html-pdf entirely to prevent future technical debt.