Optional --compress: ship native addons ~70% smaller at the same runtime speed

[jdalton]

napi build --compress ships any native addon as a single, self-loading .node that's smaller on disk at the same runtime speed. As an example: a vite 8.1.3 install pulls in two big napi natives — lightningcss and the rolldown binding — and --compress takes their footprint from ~25 MB to ~8 MB on disk (darwin-arm64).

Measured against vite 8.1.3's resolved natives (zstd, level 16):

• lightningcss 1.32.0: 8.52 MB → 2.53 MB (3.4×)
• rolldown 1.1.4 binding: 16.33 MB → 5.44 MB (3.0×)
• vite 8.1.3, both natives: 24.84 MB → 7.97 MB — ~16.9 MB off the install

Output is byte-identical and runtime speed is unchanged — it's the same binary once loaded. PoC + tests on the feat/compress-native-addons branch; numbers reproduce on Node 26.3.1 with benchmark.mts.

FAQ

What it does, and what the first load costs (nothing on a compressing filesystem)

Each compressed addon is a single self-loading file — [stub][zstd payload][footer] — that keeps its original name (no .zst/.br/.json sidecars, so a package's file list and optionalDependencies don't change). Node dlopens the small stub; the stub reads its own 24-byte footer (payload length + an fnv1a64 content hash + a magic marker), decodes the appended payload, checks the decoded bytes are a real Mach-O/ELF/PE, and loads them — forwarding napi_register_module_v1 so the consumer sees the original exports unchanged. A bad hash or a non-binary payload fails loud, so a corrupt or tampered addon never gets loaded.

On a filesystem with built-in compression (APFS, NTFS, btrfs) the stub rewrites itself compressed in place on that first load; afterwards the OS serves it decompressed on read and Node loads it directly at native speed, never unpacked again. Everywhere else it decodes into an ephemeral cache (below). Either way the decode happens once. On a compressing filesystem the first load is the same or faster than the raw file — the kernel reads fewer physical bytes — so compression adds no load penalty; the dominant ~150 ms is just the OS validating a freshly-written binary, the same cost any .node pays. The only added cost is on the ext4/xfs fallback: a one-time decode into the cache, then +0.3 ms per load (shown in the chart above).

Which compression each OS uses

The self-rewrite hands the file to the operating system's own per-file compression, so the kernel decompresses it on read with no work from the addon. Each OS exposes different codecs, and since a .node is written once and read on load, the choice favors decode speed over the last few percent of ratio.

• macOS (APFS/HFS+, decmpfs): LZVN. The fastest of the three decmpfs codecs to decompress. LZFSE packs roughly 10–15% smaller but decodes slower, and the legacy ZLIB type is slower still. LZVN comes from the system libcompression, so nothing extra ships with the addon.
• Linux (btrfs): zstd, falling back to lzo then zlib when the kernel is too old for the preferred codec. zstd both decodes faster than zlib and compresses better, so it's the best balance on Linux.
• Windows (NTFS): LZNT1 — the built-in transparent NTFS compression. It compresses the file in place and keeps the compression when the file is later rewritten, so a reinstall that overwrites the addon stays compressed. WOF (XPRESS/LZX) packs tighter, but it drops the compression the moment a file is opened for writing, so a reinstall would silently lose it.

All three are transparent: the file keeps its original logical size, a read returns the exact original bytes, and steady-state load speed is unchanged.

Does it survive moving, copying, and linking into node_modules?

The compression is an attribute of the file on the filesystem, not baked into the bytes — a normal read always returns the exact, full binary, so loading is never affected. What's preserved is the on-disk saving, and it follows the same paths a package manager already uses to populate node_modules:

• macOS (APFS): linked in by clonefile (copy-on-write) or a hardlink — both share the compressed inode, no rewrite.
• Linux (btrfs): by reflink (copy-on-write) or a hardlink — both share the compressed extents.
• Windows (NTFS): by a hardlink — the same inode, so the same compression.

A move/rename within the volume is metadata-only and keeps it. So the addon is written compressed once in the store, and every project that links it shares that one compressed copy.

Leaving a compressing filesystem — zipping it, copying onto ext4/exFAT, sending it over a network — just hands back the normal full file; smaller-on-disk is a local property, never a portable blob, and the file is never left corrupt. For that off-disk hop the --compress form is the carrier: it stays small as a file anywhere, then becomes OS-compressed again once it lands on a compressing filesystem.

Why not just shrink the Rust binary?

These binaries are already stripped + fat LTO, so there's no free size left at the Rust level. The opt-level=z build setting gets lightningcss to 3.4 MB but runs ~3× slower (transform() minifying a 1.16 MB stylesheet: ~60 → ~19 ops/sec, best-of-3). The bytes are just code at that point. Storing them compressed and unpacking once is the only thing that shrinks the published size without making it slower — the code that runs is byte-for-byte identical.

Cache location & env vars

The size win is in the published package, the npm download, and node_modules — they hold the small file. On a compressing filesystem there's no second copy at all (the addon rewrites itself in place). Where the OS can't compress, the loader decodes into a separate, optional layer that's ephemeral by default: the same OS temp dir Node's own V8 compile cache uses — the one tools like vite already turn on via module.enableCompileCache() (that defaults to <os.tmpdir()>/node-compile-cache; ours sits beside it as <os.tmpdir()>/napi-rs-native). It's content-addressed, so it's a hit until temp is cleared (e.g. a reboot), then re-decoded once. That keeps disk honest — a persistent home-dir cache would leave a machine holding the small blob plus the expanded copy, i.e. more than shipping the raw .node.

NAPI_RS_NATIVE_CACHE picks the trade:

• unset (default): ephemeral OS-temp cache — fast repeat loads within a session, disk self-bounds.
• =<path>: persist there — a CI cache volume, a tmpfs, a shared mount.
• =node_modules: the nearest node_modules/.cache (per-package).
• =workspace: the workspace root's node_modules/.cache, shared by every package — root found by its manifest (pnpm-workspace.yaml, package.json "workspaces", lerna.json, rush.json, …), falling back to the topmost node_modules.
• =0: no cache — decode to a per-process temp, unlinked right after load, so disk never holds more than the blob.

CI, depot.dev, and the native path on Linux

On CI the compressed form is a win before you tune anything: a vite 8.1.3 install pulls ~16.9 MB less native down the wire, so fresh installs are smaller and the package store holds less.

The native (FS-compressed) path needs a compressing filesystem on the path the addon lives on. macOS (APFS) and Windows (NTFS) get it for free — including GitHub Actions macOS/Windows runners and most cloud Windows/macOS instances. Linux is the gap: GitHub Actions Ubuntu and the usual AWS / Azure / GCP images run ext4/xfs, which don't compress, so they take the ephemeral-cache fallback. To opt in on Linux, mount a btrfs volume in the job and install/build onto it:

- run: |
    truncate -s 4G /tmp/fs.img && mkfs.btrfs -q /tmp/fs.img
    mkdir -p "$RUNNER_TEMP/btrfs"
    sudo mount -o loop,compress-force=zstd /tmp/fs.img "$RUNNER_TEMP/btrfs"
    sudo chown "$USER" "$RUNNER_TEMP/btrfs"
# then install/build there — the .node must live on it to self-rewrite

depot.dev accelerates runners and caching but (to my knowledge) doesn't provide a compressing filesystem, so its Linux runners are still ext4/xfs → cache fallback; the upside there is its persistent cache makes the one-time decode cheap to restore across runs.

If you'd rather just persist the decoded cache, it's a plain dir — point NAPI_RS_NATIVE_CACHE at a path you cache. Note actions/cache has no default paths (you name them), and setup-node's built-in cache covers the package store, not node_modules or temp — so it won't persist unless you add it. The payoff is small, though: restoring it saves only the ~10 ms decode (the restored file still gets OS-validated), so for most CI it's fine to just let it re-decode.

Bonus: the JS side adds up too

Separate from the native, a lot of toolchains ship their JS dist unminified for readable stack traces. That's reclaimable, and it isn't all-or-nothing — vite 8.1.3 has 1.93 MB of bundled JS:

level	dist JS	identifiers
whitespace + comments only	1.93 MB → 1.50 MB (−22%)	kept, stack traces stay readable
full minify	1.93 MB → 0.99 MB (−48%)	mangled

Strip whitespace + comments globally (names intact), or fully minify only the bundled-dependency chunks (nobody steps into chokidar/postcss internals) while leaving your own entry points readable. Combined with --compress, a full vite install goes 29.0 MB → ~11.2 MB (−61%).

Happy to open a PR — the branch carries it end to end: --compress in the build matrix (set once via napi.compress / napi.compressLevel in config), plus a build-stubs CI workflow for the per-target stubs.

[Brooooooklyn]

My first reaction was that this work should be done by the registry, but considering that the npm registry is basically no longer being maintained, I think it might also be a good choice to push this forward from the NAPI-RS side.
Overall, I think this feature is excellent. Thank you for taking the time to explore this approach. However, I still have a few concerns, and I need some time to run some experiments to confirm that this compression approach works well in various situations.

[jdalton]

@Brooooooklyn I've updated the proposal to rely on OS'd built-in filesystem compression, which offers a better experience. I'm also going to open PRs against pnpm and aube to support something similar (leverage the builtin OS filesystem compression).

[Brooooooklyn]

@jdalton After some investigation, I've found no blocking issues on my end. Please create a PR so we can move this forward together 🚢

[jdalton]

Awesome, thank you for digging into it @Brooooooklyn! Will do, asap.

[intellild]

Great idea. If package managers could support this at their level, this would benefit the entire ecosystem, including all existing packages, rather than requiring each package to solve the problem independently.

[jdalton]

@intellild 🤝 Working on that too (aube, zpm, pnpm - rust built pms first, then npm and vltpkg - js built pms)

• bench: on-disk savings + load times of AUBE_COMPRESS_STORE for vite + rspack jdx/aube#1001 (comment)
• Store native addons compressed on disk (opt-in, transparent FS compression) yarnpkg/zpm#317 (comment)

Landing in a way that supports both hybrid (so we can have it today) and regular .node for tomorrow.