pdf-render-pool
Turn HTML into PDFs from a Node process, with one warm Chromium and a cap on how many render at once.
Quick start
npm install pdf-render-pool puppeteer
const { createPdfRenderPool } = require('pdf-render-pool');
// Create once per process and reuse it.
const pool = createPdfRenderPool({ concurrency: 2, maxQueue: 100 });
const pdf = await pool.renderPdf('<h1>Invoice #42</h1>', { format: 'A4' });
// On shutdown: finishes running and queued renders first.
await pool.close();
Requires Node 20+ and Puppeteer 22+.
What it handles
- Overload: extra renders queue, and
maxQueueorqueueTimeoutreject them when there are too many. - Stuck pages: one
timeoutcovers the render, including pages stuck in a script loop. - Browser failures: a browser that crashes or stops responding is replaced, with optional
retries. - Isolation: each render gets its own browser context, closed afterwards.
- Memory:
idleTimeoutandmaxRendersPerBrowserrelease or recycle the browser. - Bad responses: a 404 or 500 rejects instead of becoming a PDF of the error page.
Benchmarks
One-page A4 report on a 2-core laptop, measured on v0.2.x. Numbers vary by machine.
| Job | Mean | p95 |
|---|---|---|
| Launch Chromium per PDF (no pool) | 1862 ms | 2190 ms |
| Warm render, isolated (default) | 657 ms | 885 ms |
Warm render, isolate: false | 465 ms | 667 ms |
Rendering user content
Rendered HTML runs in a real browser on your server and can request anything your server can reach. Chromium's sandbox is also off by default so that it starts on typical servers. If users can influence the HTML or URL, read the security notes and use requestFilter and sandbox: true.
When to use something else
- Gotenberg for a separate Docker service, Office conversion, merging or PDF/A.
- puppeteer-cluster for crawling or general browser jobs.
- browserless for browsers shared across many services.