Automate HTML to PDF Conversion with Node.js and PythonConverting HTML to PDF is a common requirement: generating invoices, reports, tickets, documentation, or preserving web pages in a fixed-layout format. Automating this conversion removes manual steps, ensures consistency, and integrates PDF generation into backend workflows, serverless jobs, and CI/CD pipelines. This article covers why you’d automate HTML-to-PDF conversion, compares common approaches, and provides practical, production-ready examples in both Node.js and Python — including tips for styling, performance, headless-browser vs library trade-offs, and deployment considerations.
Why automate HTML → PDF?
- Consistency: Programmatic rendering ensures identical output every time.
- Scalability: Automatic generation supports batches and high-throughput systems.
- Integration: PDFs can be created on demand within APIs, scheduled jobs, or event-driven flows.
- Control: You can programmatically inject data, apply templates, and adjust layout for different devices or print sizes.
Common approaches
There are two principal approaches for converting HTML to PDF:
-
Headless browser rendering (Chromium / Puppeteer / Playwright)
- Renders HTML exactly as a browser would, including JavaScript, external fonts, and complex CSS.
- Best for pages that rely on client-side scripts or dynamic content.
- Higher memory/CPU cost, but excellent fidelity.
-
Library-based rendering (wkhtmltopdf, WeasyPrint, PDFKit, PrinceXML)
- Uses an engine that converts HTML/CSS to PDF without a full browser.
- Often faster and lighter, but may lack full CSS/JS support or produce layout differences.
Comparison table:
| Approach | Pros | Cons |
|---|---|---|
| Headless browser (Puppeteer/Playwright) | High fidelity, supports JS, modern CSS | Higher resource usage, more complex deployment |
| wkhtmltopdf / WeasyPrint / PrinceXML | Lighter, faster for simple pages | Limited JS support, CSS differences, licensing costs (PrinceXML) |
| Library PDF generators (PDFKit, ReportLab) | Programmatic control, fine-grained PDF ops | Need manual layout; not HTML-driven |
Key considerations before you build
- Input types: raw HTML strings, local HTML files, or remote URLs.
- CSS for print: use @media print rules, page-break-* properties, and size settings (A4, letter).
- Fonts: embed or ensure availability; web fonts may require extra configuration.
- Images: prefer absolute URLs or embed images as base64 for offline generation.
- Concurrency and resource limits: headless browsers consume memory — pool browser instances.
- Security: sanitize HTML if it comes from untrusted sources to avoid XSS or resource abuse.
- Pagination: handle headers/footers and page breaks for multi-page documents.
Example 1 — Node.js with Puppeteer (headless Chromium)
Puppeteer provides a straightforward way to render pages in headless Chromium and save them as PDFs. Below is a minimal, production-ready example that accepts HTML (string or URL), supports headers/footers, and uses a browser pool for concurrency.
Prerequisites:
- Node.js 18+
- npm install puppeteer generic-pool express
File: package.json (relevant deps)
{ "dependencies": { "express": "^4.18.2", "generic-pool": "^3.8.2", "puppeteer": "^21.0.0" } } File: browserPool.js
const puppeteer = require('puppeteer'); const genericPool = require('generic-pool'); const factory = { create: async () => { return puppeteer.launch({ args: ['--no-sandbox', '--disable-setuid-sandbox'], headless: true, }); }, destroy: async (browser) => { await browser.close(); }, }; const opts = { max: 4, min: 1 }; const pool = genericPool.createPool(factory, opts); module.exports = pool; File: server.js
const express = require('express'); const pool = require('./browserPool'); const app = express(); app.use(express.json({ limit: '5mb' })); // accept HTML payloads app.post('/generate-pdf', async (req, res) => { const { html, url, options } = req.body; if (!html && !url) return res.status(400).send('Provide html or url'); const browser = await pool.acquire(); try { const page = await browser.newPage(); if (html) { await page.setContent(html, { waitUntil: 'networkidle0' }); } else { await page.goto(url, { waitUntil: 'networkidle0' }); } const pdfBuffer = await page.pdf({ format: options?.format || 'A4', printBackground: true, margin: options?.margin || { top: '20mm', bottom: '20mm' }, displayHeaderFooter: !!options?.header || !!options?.footer, headerTemplate: options?.header || '', footerTemplate: options?.footer || '', }); res.type('application/pdf').send(pdfBuffer); await page.close(); } catch (err) { console.error(err); res.status(500).send('PDF generation failed'); } finally { await pool.release(browser); } }); app.listen(3000, () => console.log('Server listening on :3000')); Notes:
- Use networkidle0 to wait for async JS. Adjust for heavy pages.
- Provide header/footer HTML templates; Puppeteer allows limited template tokens.
- Use a pool to avoid launching a new Chromium per request.
Example 2 — Python with Playwright (headless Chromium)
Playwright supports multiple browsers and has a clean Python API. This example shows using Playwright in a fast, async server (FastAPI) with simple pooling via a singleton browser instance.
Prerequisites:
- Python 3.9+
- pip install fastapi uvicorn playwright aiofiles
- playwright install chromium
File: main.py
from fastapi import FastAPI, HTTPException, Request from playwright.async_api import async_playwright import asyncio app = FastAPI() playwright = None browser = None browser_lock = asyncio.Lock() @app.on_event("startup") async def startup(): global playwright, browser playwright = await async_playwright().start() browser = await playwright.chromium.launch(headless=True, args=['--no-sandbox']) @app.on_event("shutdown") async def shutdown(): global playwright, browser if browser: await browser.close() if playwright: await playwright.stop() @app.post("/generate-pdf") async def generate_pdf(request: Request): payload = await request.json() html = payload.get("html") url = payload.get("url") if not html and not url: raise HTTPException(status_code=400, detail="Provide html or url") async with browser_lock: # serialize short-lived page creation to limit resource spikes page = await browser.new_page() try: if html: await page.set_content(html, wait_until="networkidle") else: await page.goto(url, wait_until="networkidle") pdf_bytes = await page.pdf(format=payload.get("format", "A4"), print_background=True) return Response(content=pdf_bytes, media_type="application/pdf") finally: await page.close() Notes:
- Playwright can run multiple contexts/pages; use locks or a queue to manage concurrency on limited hosts.
- FastAPI + Uvicorn works well for async workloads.
Example 3 — Python with WeasyPrint (no browser)
WeasyPrint converts HTML/CSS to PDF without a full browser. It’s lighter but limited with JavaScript.
Install:
- pip install WeasyPrint
Simple script:
from weasyprint import HTML def html_to_pdf(html_str, out_path='output.pdf'): HTML(string=html_str).write_pdf(out_path, presentational_hints=True) if __name__ == '__main__': sample_html = '<html><body><h1>Hello</h1><p>PDF from WeasyPrint</p></body></html>' html_to_pdf(sample_html, 'weasy_output.pdf') When to use:
- Static templates rendered server-side (Jinja2, Django templates).
- When you don’t need JS execution.
Styling for print — practical tips
- Use @media print to customize layout for PDF.
- Use CSS page-break-before/after/inside to control pagination.
- Set sizes: @page { size: A4; margin: 20mm; }.
- Avoid viewport-width dependent layouts unless you set the viewport width in the headless browser to match the printed page.
- For headers/footers with Puppeteer/Playwright, provide simple HTML templates; complex scripts won’t run inside header/footer templates.
Example CSS:
@page { size: A4; margin: 20mm; } @media print { nav, .no-print { display: none; } body { -webkit-print-color-adjust: exact; } h1 { page-break-before: always; } } Performance & scaling strategies
- Reuse browser instances or use a pool to avoid frequent Chromium startup.
- Limit concurrent pages per browser (2–10 depending on memory).
- For high throughput, use multiple worker processes or container replicas behind a job queue (RabbitMQ, Redis Queue).
- Cache generated PDFs when inputs are identical (hash input HTML + options).
- Monitor memory and CPU; headless browsers can leak if pages aren’t closed properly.
Security and sandboxing
- Sanitize user-submitted HTML to remove scripts if you don’t want them to run.
- Run browsers with –no-sandbox only in controlled environments; prefer proper container isolation (gVisor, Firecracker) or OS-level sandboxes.
- Limit network access for the rendering process if you don’t want it to fetch external resources.
- Set timeouts for page loading and PDF generation to avoid resource hang-ups.
Testing, debugging, and visual diffs
- Save intermediate screenshots to debug layout differences:
- page.screenshot({ fullPage: true })
- Use visual diff tools (Percy, Resemble.js) to detect unintended changes in generated PDFs.
- Verify fonts and images render correctly in CI environments by installing required system fonts or bundling them.
Deployment tips
- Containerize with a lightweight Chromium base (e.g., use official Playwright Docker images or install Chromium in your image).
- Ensure required system libraries are present (libnss3, fonts, etc.) for headless Chromium.
- Use autoscaling and job queues for variable load.
- Monitor latency and error rates; log page console errors when debugging.
Troubleshooting common issues
- Blank PDF: ensure page.waitUntil is appropriate (networkidle vs load), and resources are accessible.
- Missing fonts: install fonts in the container or use base64-embedded fonts.
- Long generation times: pre-render heavy JS server-side or optimize the page.
- Headers/footers not rendering: templates must be simple HTML (no external scripts/styles).
Conclusion
Automating HTML-to-PDF conversion unlocks consistent, reproducible document generation for invoices, reports, and more. Use headless browsers like Puppeteer or Playwright when fidelity to the browser rendering (JS, complex CSS) matters. Use lighter libraries like WeasyPrint or wkhtmltopdf for simpler, server-side-rendered templates. Plan for concurrency, resource limits, and security when deploying in production.
If you want, I can:
- provide a Dockerfile for any of the examples,
- expand the Node.js server to include authentication and rate limiting,
- or create a Jinja2/Handlebars template example and a sample pipeline for CI.
Leave a Reply