Using npm Packages

Pure resolves npm packages at compile time, not at runtime. When you import a package, Pure includes its code in the compiled binary. You do not need node_modules present on the machine running the binary.

How package resolution works

1. Run npm install in your project directory as usual. This populates node_modules.
2. Run pure build. Pure reads node_modules and includes all imported packages in the binary.
3. The compiled binary contains the package code — node_modules is not needed at runtime.

You can also point npm install at the Pure registry if you want access to Pure-compiled native packages. See Configure npm.

Pure-compiled packages vs. standard npm packages

Package type	How it works
Standard JavaScript/TypeScript npm packages	Included verbatim in the binary. Works for most packages.
Pure-compiled packages	Compiled to native code; distributed as .node add-ons from the Pure registry. Maximum performance.
Native add-ons (N-API)	Works if the add-on targets Node-API; does not work if it uses V8 internal headers.

Installing packages

npm install express zod

No special steps needed. After npm install, run pure build normally.

Compatibility

Most pure-JavaScript npm packages work without modification. Packages that:

• Use eval or new Function() — will not work. See Not supported.
• Use unsupported Node built-ins — may not work. See Node compatibility.
• Use native add-ons — may work depending on the add-on. See below.

Native add-ons

Add-ons built with Node-API (the stable C API) generally work. Add-ons that use V8 C++ headers or Node.js internal headers do not.

Known to work:

• better-sqlite3
• sharp (image processing)
• @napi-rs/* packages

Known issues:

• Packages that detect the runtime via process.versions.node may misbehave if they require a specific version. You can often work around this by patching the version check.

For a detailed breakdown, see npm Packages → Native add-ons (coming soon).

Troubleshooting package issues

If a package fails to compile or behaves unexpectedly at runtime:

1. Check Not supported for known limitations.
2. Check Troubleshooting → Compile failures for how to read compiler output.
3. Search the issue tracker for the package name.
4. File a bug report with a minimal reproduction. See Support.