pdf-raster

Runtime and environment

Where pdf-raster runs, how it behaves under concurrent load and how much memory it needs.

Supported runtimes

RuntimeSupported
Node.js 24 or newerYes
BunYes
Browsers and React Client ComponentsNo
Edge runtimes, such as Vercel Edge FunctionsNo
WebAssemblyNo

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:

next.config.ts
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.

  1. 01

    Input

    path, Buffer, Uint8Array or ArrayBuffer

  2. 02locked

    Render

    PDFium, one page at a time behind a process-wide lock

  3. 03parallel

    Encode

    PNG, JPEG or WebP on up to 4 threads per call

  4. 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 bytes

A 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.

On this page