Server Usage
PDF generation is CPU-intensive. This page covers what to consider when using the library in a Node.js server, and when to use the Docker server instead.
How it works in the browser vs Node.js
In the browser, the library uses Web Workers automatically to avoid blocking the UI. No extra setup is needed.
In Node.js, generatePdf and generatePdfBase64 block the event loop during generation. This means that while a PDF is being generated, your server cannot handle other incoming requests. For a single request at a time this is fine, but under concurrent load it becomes a bottleneck.
Handling concurrency in Node.js
If your Node.js server needs to generate PDFs concurrently, you have two options:
Option 1: Worker threads
Use Node.js worker threads to offload PDF generation to separate threads. This keeps your main thread responsive.
You can use preloadEngine and setPreloadedWasmBinary to load the WASM binary once in the main thread and share it across workers, avoiding redundant downloads:
import { preloadEngine, setPreloadedWasmBinary } from "@pdfsamurai/pdfsamurai-js";
// Main thread: load once
const binary = await preloadEngine();
// Pass `binary` to each worker thread, then inside the worker:
setPreloadedWasmBinary(binary);
Option 2: PDFSamurai Docker Server
If you'd rather not manage worker threads yourself, use the PDFSamurai Docker Server. It handles worker threads, request queuing, and concurrency internally — you just send HTTP requests.
This is also the right choice if your backend is not JavaScript.
When to use what
| Scenario | Recommendation |
|---|---|
| Browser app | Use the library directly — Web Workers handle concurrency |
| Node.js, low traffic | Use the library directly — blocking is negligible |
| Node.js, concurrent PDFs | Use worker threads or the Docker server |
| Non-JavaScript backend | Use the Docker server |
| Microservice architecture | Use the Docker server as a dedicated PDF service |