Installation
Install pdf-raster and check that it runs on your platform.
npm install pdf-rasterRequirements
- 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:
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.