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 installDownload PDFium into the local cache:
bun run pdfium:downloadBuild the native package:
bun run --filter pdf-raster buildRun the tests. They rebuild the package, then run under Bun and Node.js and check concurrent initialization:
bun run --filter pdf-raster testRepository layout
| Directory | Contents |
|---|---|
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
- Run
bun run pdfium:downloadto refresh the PDFium cache. - Rebuild with
bun run --filter pdf-raster build. - 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-muslUse 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
mainopens or updates a "Version Packages" pull request. - Merging that pull request publishes all 9 packages,
pdf-rasterand its 8 platform packages, frommainwith npm provenance. The workflow then creates thevX.Y.Ztag and a GitHub release whose notes are that version'score/CHANGELOG.mdsection. - Pushes to
mainbuild 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-runchecks the packaging without publishing. It needs all 8 native artifacts incore/artifacts/, which you can download from a Release workflow run.
Running npm publish in core/ fails on purpose. Publish only through the
release script.