pdf-raster

Installation

Install pdf-raster and check that it runs on your platform.

npm install pdf-raster

Requirements

  • Node.js 24 or newer, or Bun
  • macOS, Linux, or Windows, on x64 or arm64

On Linux there are separate packages for glibc distributions, such as Debian and Ubuntu, and for musl distributions, such as Alpine. The node:24-alpine Docker image works without extra packages.

What gets installed

pdf-raster lists one optional dependency per platform, such as pdf-raster-darwin-arm64, pdf-raster-linux-x64-gnu or pdf-raster-linux-x64-musl. Your package manager installs only the one that matches your machine. That package holds the compiled addon and the PDFium shared library it loads, so you do not install PDFium yourself.

Server code only

The package loads native code. Do not import it from browser bundles, React Client Components or Edge functions.

Next.js

Add the package to serverExternalPackages so Next.js loads it from node_modules at runtime instead of bundling it:

next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  serverExternalPackages: ["pdf-raster"],
};

export default nextConfig;

Call it only from Node.js route handlers, Server Actions or other server code. Runtime and environment explains why.

Check the install

Render the first page of any PDF:

import { convert } from "pdf-raster";

const [page] = await convert("./any.pdf", { pages: [0] });
console.log(page.mimeType, page.width, page.height);
// image/png 2550 3300 (a US letter page at the default 300 DPI)

If the call throws PDFIUM_UNAVAILABLE, the platform package is missing or could not load. See Errors and troubleshooting.

On this page