A persistent, concurrency-capped headless-Chromium HTML→PDF renderer built on Puppeteer.
Launching and tearing down a full Chromium for every PDF costs ~1-2 seconds
and ~150-300MB of RSS. pdf-render-pool keeps one browser warm and gives
each render its own page, so a render only pays for opening a tab — plus a
concurrency cap so a burst of PDF requests queues instead of OOMing your
server.
Project page · Changelog · Security
- Concurrency-capped — at most
concurrencyrenders run at once (default 2); the rest queue FIFO. - Back-pressure — optionally cap the queue (
maxQueue) so overload fails fast withEQUEUEFULLinstead of piling up. - Bounded — once a render has a slot, one
timeoutdeadline covers browser launch, page creation, content load and PDF generation, even if the page is stuck in a script loop. Time spent queued is limited separately byqueueTimeout. - Self-healing — a browser that crashes, hangs while launching or stops opening pages is replaced. Renders running on a crashed browser fail with
EBROWSERCRASHEDunless you setretries. - Isolated — every render runs in its own browser context (separate cookies, localStorage and cache), always closed afterwards, so renders can't leak pages or state into each other. Opt out with
isolate: false. - Memory-friendly — optionally close the browser when idle (
idleTimeout), or recycle it after N renders (maxRendersPerBrowser) without interrupting renders in flight.
npm install pdf-render-pool puppeteerRequires Node 20+ and Puppeteer 22+. Upgrading from 0.2? See the changelog.
puppeteer is a peer dependency — bring your own version (or puppeteer-core
with an explicit executablePath, see below) so this package doesn't force a
particular Chromium download strategy on you. No other runtime dependencies.
const { createPdfRenderPool } = require('pdf-render-pool');
// or: import { createPdfRenderPool } from 'pdf-render-pool';
// Create the pool ONCE per process and reuse it everywhere — it holds one
// persistent browser instance.
const { renderPdf, renderPdfFromUrl, close } = createPdfRenderPool();
// From an HTML string
const invoice = await renderPdf('<h1>Invoice #42</h1>', { format: 'A4' });
// From a URL
const page = await renderPdfFromUrl('https://example.com/report', {
format: 'A4',
waitUntil: 'networkidle0',
});
// On graceful shutdown (finishes running and queued renders first):
await close();Returns { renderPdf, renderPdfFromUrl, renderPdfStream, renderPdfStreamFromUrl, closeBrowser, close, stats }. Invalid options throw a RangeError.
createPdfRenderPool({
concurrency: 4, // max renders at once (default 2)
maxQueue: 100, // max renders waiting for a slot (default Infinity)
queueTimeout: 10_000, // max ms to wait for a slot (default Infinity)
idleTimeout: 5 * 60_000, // close Chromium after 5 min without renders (default 0 = never)
maxRendersPerBrowser: 500, // recycle Chromium after 500 renders (default 0 = never)
launchTimeout: 30_000, // abandon a browser launch after this long (default 30000)
retries: 1, // retry a render after a browser crash (default 0)
waitUntil: 'domcontentloaded', // default load event for every render
assetTimeout: 3000, // ms images/fonts get before being cancelled (default 3000)
isolate: true, // fresh browser context per render (default true)
sandbox: false, // keep Chromium's sandbox on (default false, see Security)
allowFileUrls: false, // allow file: URLs in renderPdfFromUrl (default false)
allowHttpErrors: false, // print pages with status >= 400 (default false)
requestFilter: (url) => true, // allow or block each request the page makes
beforeRender: async (page) => {}, // runs on each page before content loads
puppeteerModule: 'puppeteer', // or 'puppeteer-core'
launchOptions: { // merged over the sandbox-safe defaults
executablePath: '/usr/bin/chromium',
},
onInfo: (msg) => console.log(msg),
onWarn: (msg) => console.warn(msg),
onEvent: (event) => {}, // { type: 'launch' | 'crash' | 'recycle' | 'retry' | 'idle-close' }
});Default launch flags (--no-sandbox, --disable-setuid-sandbox,
--disable-dev-shm-usage, --disable-gpu) target typical Linux
servers/containers where Chromium runs with a tiny /dev/shm. Override them via
launchOptions, and read Security about the sandbox flags.
maxRendersPerBrowser caps how many renders one Chromium serves. Once it is
reached, new renders go to a freshly launched browser and the old one closes
after its in-flight renders finish, so recycling never interrupts a render.
options are forwarded to Puppeteer's
page.pdf() (format, margin,
landscape, printBackground — defaults to true — …) plus:
| Option | Default | Description |
|---|---|---|
timeout |
30000 |
One deadline (ms) for the render, from when it gets a slot, including a browser launch and any retries. |
queueTimeout |
pool's queueTimeout |
Max ms to wait for a slot. |
signal |
AbortSignal that cancels the render, queued or running. |
|
retries |
pool's retries |
Retries after a browser crash, within the same timeout. |
beforeRender |
pool's beforeRender |
async (page) => {} before content loads: cookies, auth headers, viewport, emulateMediaType. |
waitForSelector |
Wait for this selector after loading, before printing. | |
waitForFunction |
Wait for this page expression to be truthy before printing. | |
requestFilter |
pool's requestFilter |
(url, request) => boolean. Anything but a truthy answer blocks the request. |
allowHttpErrors |
pool's allowHttpErrors |
URL renders only: print pages with status 400 or above instead of rejecting. |
waitUntil |
pool's waitUntil |
'domcontentloaded', 'load', 'networkidle0' or 'networkidle2'. |
assetTimeout |
pool's assetTimeout |
With 'domcontentloaded': ms to let images/fonts finish before cancelling them (see below). |
For large PDFs. The render keeps its slot until the stream is read or destroyed,
and timeout still applies, so read it promptly.
Use this at process shutdown. New renders reject with ECLOSED, running and
queued renders finish (for at most timeout ms), then the browser closes. With
drain: false they fail with ECLOSED straight away. The pool can't be reused.
Also available as await using pool = createPdfRenderPool().
Closes the current browser now, failing renders that are using it. The pool stays usable: queued and later renders launch a new browser. Safe to call when none was launched.
Returns { active, queued, browser, closed, completed, failed, launches, crashes, recycles },
where browser is 'none', 'launching' or 'ready'. Handy for health checks and metrics.
err.code |
When |
|---|---|
ETIMEDOUT |
The render exceeded timeout, or a launch exceeded launchTimeout. |
EQUEUEFULL |
maxQueue renders were already waiting. |
EQUEUETIMEOUT |
The render waited longer than queueTimeout for a slot. |
EHTTPSTATUS |
The URL responded with status 400 or above. See err.status. |
EBLOCKEDURL |
The URL's protocol isn't allowed. |
EBROWSERCRASHED |
Chromium died during the render. See err.cause. |
ELAUNCH |
Chromium failed to start. |
ECLOSED |
The pool or browser was closed. |
ABORT_ERR |
The render's signal was aborted. |
Rendered HTML runs in a real browser on your server. If a user can influence the HTML or URL, even through a name on a certificate, treat it as untrusted:
- Internal network access (SSRF). Pages can request anything your server can
reach, such as localhost services or cloud metadata endpoints. Escape user values
in templates and use
requestFilterto allow only the hosts you expect. A filter that checks hostnames doesn't stop DNS rebinding, so also restrict outbound traffic at the network level if the risk matters to you. - The sandbox is off by default.
--no-sandboxlets Chromium start on typical servers and containers, but a browser exploit would then reach your whole user account. Setsandbox: truewhere your system supports it, and run in a container as a non-root user. - Local files.
renderPdfFromUrlrefusesfile:URLs unless you setallowFileUrls. - Scripts. If you don't need them, turn them off:
beforeRender: (page) => page.setJavaScriptEnabled(false).
Call close() on shutdown:
process.on('SIGTERM', async () => {
server.close();
await pool.close({ timeout: 10_000 });
process.exit(0);
});In Express, stop rendering when the client leaves, and return 503 under overload:
app.get('/report.pdf', async (req, res) => {
const controller = new AbortController();
res.on('close', () => controller.abort());
try {
const pdf = await pool.renderPdf(reportHtml(), { format: 'A4', signal: controller.signal });
res.type('application/pdf').send(pdf);
} catch (err) {
if (err.code === 'ABORT_ERR') return;
res.sendStatus(err.code === 'EQUEUEFULL' || err.code === 'EQUEUETIMEOUT' ? 503 : 500);
}
});Slim Linux images usually lack Chromium's libraries and fonts. On Debian or Ubuntu,
install fonts-noto and fonts-noto-color-emoji or the PDF may show empty boxes,
and see Puppeteer's Docker guide for the libraries.
- Gotenberg if you want a separate Docker service, or need Office conversion, merging or PDF/A.
- puppeteer-cluster for crawling or general browser jobs rather than just PDFs.
- browserless for hosted or shared browsers used from many services.
This package fits when you want PDFs from inside a Node process with no extra service.
These were measured on v0.2.x and have not been rerun on 0.3.0.
One-page A4 report (inline CSS, 30-row table), measured with
bench/benchmark.js on an Intel i7-6500U laptop
(2 cores / 4 threads, 8 GB RAM), Windows 10, Node 24, Puppeteer 25.3.
| Job | Mean | p50 | p95 |
|---|---|---|---|
| Launch Chromium + render + close, per PDF (no pool) | 1862 ms | 1862 ms | 2190 ms |
| Pool, first render (includes browser launch) | 1690 ms | ||
Pool, warm render (isolate: true, default) |
657 ms | 625 ms | 885 ms |
Pool, warm render (isolate: false) |
465 ms | 442 ms | 667 ms |
A warm render is ~2.8× faster than launching Chromium per PDF (~4× without isolation). Per-render isolation costs ~190 ms on this machine.
Burst of 40 simultaneous renders:
concurrency |
Wall time | PDFs/s |
|---|---|---|
| 1 | 28.3 s | 1.4 |
| 2 | 31.8 s | 1.3 |
| 4 | 24.8 s | 1.6 |
Rendering is CPU-bound, so on a 2-core machine extra concurrency barely helps.
Set concurrency to roughly the cores you can spare, and use maxQueue to cap
latency instead.
Other behaviour:
- Back-pressure (
concurrency: 2,maxQueue: 5, 20 simultaneous requests): 7 rendered, 13 rejected immediately withEQUEUEFULL. - Image host that never responds: 3.5 s with defaults (3 s
assetTimeout, then print without it); 1.0 s withassetTimeout: 500;waitUntil: 'networkidle0'fails withTimeoutErrorat thetimeout.
Numbers vary with hardware and OS (Chromium usually launches faster on Linux); run the benchmark on your own machine:
npm install --no-save puppeteer
node bench/benchmark.jsbench/memory.js: 3,000 renders of a heavy page (400-row
table + SVG chart), concurrency 2, total memory of all Chromium processes
(same laptop, Windows):
| Start | After 3,000 renders | Peak | |
|---|---|---|---|
| One warm browser, no recycling | 367 MB | 375 MB | 377 MB |
maxRendersPerBrowser: 500 |
360 MB | back to baseline at each recycle | 371 MB |
Closing each render's isolated context frees almost everything it used, so a
warm browser stays nearly flat. maxRendersPerBrowser is a safety valve for
pages that do grow Chromium's memory; every render succeeded across recycles.
node bench/memory.js [renders=3000] [maxRendersPerBrowser=500]HTML templates are expected to be self-contained (inline CSS). If a template
embeds a remote image and that host is slow or unreachable, waiting for
networkidle0 would hang the whole render — and the shared concurrency slot
— until timeout. With domcontentloaded, the pool gives images and fonts up to
assetTimeout (default 3000 ms) to finish, then cancels whatever is still
pending (window.stop()) and prints. A slow logo still makes it into the PDF;
a dead one renders blank after at most assetTimeout instead of stalling the
pool. (Without the cancel, Puppeteer's page.pdf() would keep waiting on it.)
To wait for something specific, such as a chart, use waitForSelector or
waitForFunction. If your content must be complete, set waitUntil: 'load' or
'networkidle0' and the render fails on timeout rather than printing
without it.
Need independent concurrency budgets for different kinds of PDFs (e.g. certificates vs. large reports)? Create more than one pool — each gets its own browser instance and its own queue:
const certPool = createPdfRenderPool({ concurrency: 4 });
const reportPool = createPdfRenderPool({ concurrency: 1, maxQueue: 10 });- Node 20+ and Puppeteer 22+ are required.
renderPdfFromUrlrejects status 400 and above withEHTTPSTATUS. SetallowHttpErrors: trueto print those pages.file:URLs needallowFileUrls: true, and other non-HTTP URLs are refused.- Invalid options and input now throw, including
timeout: 0. - Replace
closeBrowser()withclose()in shutdown code. - Puppeteer's timeout errors now also have
code: 'ETIMEDOUT'.
npm ci
npm test
npm run test:integrationnpm test uses a fake browser; test:integration uses real Chromium.
To release, update the version and changelog, then push a vX.Y.Z tag. The release workflow publishes to npm using the NPM_TOKEN repository secret.
mcqplex.com uses pdf-render-pool to render exam
reports, student report cards and competition certificates. The package was
extracted from its PDF renderer.
MIT