Runtime and environment
Where pdf-raster runs, how it behaves under concurrent load and how much memory it needs.
Supported runtimes
| Runtime | Supported |
|---|---|
| Node.js 24 or newer | Yes |
| Bun | Yes |
| Browsers and React Client Components | No |
| Edge runtimes, such as Vercel Edge Functions | No |
| WebAssembly | No |
Prebuilt packages cover macOS, Linux (glibc and musl, so Alpine works) and Windows, each on x64 and arm64.
Why it only runs on the server
pdf-raster loads a compiled .node addon and a PDFium shared library from
disk. Browsers and Edge runtimes cannot load native code, so the package must
stay in server code.
Next.js
Next.js bundles server code by default, and bundling breaks the paths to the
addon and to PDFium. List the package in serverExternalPackages so Next.js
loads it from node_modules instead:
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
serverExternalPackages: ["pdf-raster"],
};
export default nextConfig;Use the Node.js runtime
Route handlers that import pdf-raster must run on the Node.js runtime. Add
export const runtime = "nodejs" if your app defaults to Edge.
Concurrency and memory
PDFium is not thread-safe. pdf-raster loads documents and renders pages behind
one lock shared by the whole process. Concurrent convert() calls are safe,
and they take turns rendering.
Encoding does not need the lock. Each call encodes its pages on up to 4 worker threads. A call releases the lock as soon as its last page is rendered, so the next call can start rendering while the earlier pages are still encoding.
- 01
Input
path, Buffer, Uint8Array or ArrayBuffer
- 02locked
Render
PDFium, one page at a time behind a process-wide lock
- 03parallel
Encode
PNG, JPEG or WebP on up to 4 threads per call
- 04
Result
ConvertedPage[] with bytes, size and DPI
To bound memory, the process holds at most 8 rendered pages (raw RGBA frames) at once, however many calls are running. Estimate the peak with:
8 × width × height × 4 bytesA US letter page at 300 DPI is 2550 × 3300 pixels, so the peak is about 270 MB. The figure grows with page area and with the square of the DPI.
Untrusted input
If a client can choose the DPI, or can upload PDFs with very large pages, set
maxPixels. pdf-raster then rejects any page whose width times height exceeds
the limit with INVALID_OPTIONS, before it allocates the bitmap.
await convert(upload, {
dpi: requestedDpi,
maxPixels: 100_000_000,
});pdf-raster also rejects pages that would render wider or taller than 65,535
pixels, with or without maxPixels.
If the library fails to load
A PDFIUM_UNAVAILABLE error means the addon or the PDFium library could not
load. See Errors and troubleshooting.