pdf-raster

Local development

Build pdf-raster from source, run its tests and release a new version.

This page is for working on pdf-raster itself. To use the package, start with Installation.

Prerequisites

  • Bun 1.4.2, the version pinned in packageManager
  • Rust, stable toolchain
  • Node.js 24 or newer

Build and test

Install dependencies:

bun install

Download PDFium into the local cache:

bun run pdfium:download

Build the native package:

bun run --filter pdf-raster build

Run the tests. They rebuild the package, then run under Bun and Node.js and check concurrent initialization:

bun run --filter pdf-raster test

Repository layout

DirectoryContents
core/The published pdf-raster package, in Rust and TypeScript
docs/This site, built with Next.js and Fumadocs
benchmark/Comparisons against pdfjs-dist
example/A demo app that uses the local workspace package
consumer/A minimal Next.js app that installs pdf-raster from npm

Environment variables

Prop

Type

When the native build breaks

  1. Run bun run pdfium:download to refresh the PDFium cache.
  2. Rebuild with bun run --filter pdf-raster build.
  3. Run bun run --filter pdf-raster test.

If convert() still throws PDFIUM_UNAVAILABLE, check that PDFIUM_LIB_PATH is unset or points to a library built for your platform.

Building for Alpine

The musl targets build inside an Alpine container, the same way the Release workflow builds them. The container installs Linux dependencies into node_modules and core/target, so run it in a fresh clone rather than your working copy, on a host of the target architecture:

docker run --rm -v "$PWD:/work" -w /work node:24-alpine \
  sh scripts/build-musl.sh linux-arm64-musl

Use linux-x64-musl on an x64 host. The script builds the addon, stages PDFium and runs the test suite in the container. The artifact lands in core/artifacts/.

Releasing

  • Every change that affects the package needs a changeset. Create one with bun run changeset. CI fails without it.
  • Merging to main opens or updates a "Version Packages" pull request.
  • Merging that pull request publishes all 9 packages, pdf-raster and its 8 platform packages, from main with npm provenance. The workflow then creates the vX.Y.Z tag and a GitHub release whose notes are that version's core/CHANGELOG.md section.
  • Pushes to main build the native targets only when they are about to be published: no changesets are pending and the core version is not on npm. Other pushes only update the "Version Packages" pull request, or do nothing.
  • Running the Release workflow by hand (workflow_dispatch) on another branch builds and smoke-tests all 8 targets without publishing.
  • bun run release:publish -- --dry-run checks the packaging without publishing. It needs all 8 native artifacts in core/artifacts/, which you can download from a Release workflow run.

Running npm publish in core/ fails on purpose. Publish only through the release script.

On this page