Building native addons, prebuilds, and when not to: WASM and the alternatives

How addons build: node-gyp and binding.gyp

Why does installing a single npm package sometimes drag in a full C++ build? The answer is node-gyp — and knowing the mechanics tells you exactly why the hook’s install explosion happened and how prebuilds prevent it.

When you install a native addon without precompiled binaries, npm runs its install script, which usually calls node-gyp — Node’s build orchestrator. node-gyp reads a binding.gyp file (a Python-ish JSON dialect inherited from Chromium’s GYP), generates platform build files (a Makefile, an Xcode project, or an MSVC project), and invokes the host compiler to produce the .node binary.

# binding.gyp — describes what to compile and how
{
  "targets": [
    {
      "target_name": "addon",
      "sources": [ "src/addon.cc", "src/resize.cc" ],
      "include_dirs": [
        "<!@(node -p \"require('node-addon-api').include\")"
      ],
      "cflags_cc": [ "-O3", "-std=c++17" ]
    }
  ]
}

The implication is the trap from the hook: building from source needs a full toolchain on the installing machine — node-gyp itself requires Python, plus a C/C++ compiler (GCC/Clang, or MSVC on Windows) and Node’s headers for the running version. That’s fine on a dev box you control, but it makes the addon fragile everywhere else: minimal Docker images without build tools fail, Alpine’s musl libc breaks glibc-built assumptions, Windows needs the Visual Studio build tools, and even on a working setup every npm install pays minutes of compile time. A native dependency turns install from “download files” into “compile a C++ project,” with all the platform variance that implies.

Prebuilds: ship the binary, skip the compiler

The fix for install-time pain is to not compile at install — ship precompiled binaries inside the package, one per platform/architecture, and at install time just pick the matching one. Two ecosystems do this: node-pre-gyp (downloads prebuilt binaries from a host like S3/GitHub Releases) and prebuildify (bundles all the prebuilt binaries into the published npm tarball, so install does zero network and zero compile — it just copies the right file). prebuildify is the simpler, more reliable model: no download server to depend on, fully offline installs.

// package.json — prebuildify produces prebuilds/<platform>-<arch>/*.node
{
  "scripts": {
    // run once on each target platform (or in CI matrix) before publishing:
    "prebuild": "prebuildify --napi --strip"
  }
}

Here is where Node-API earns its keep a second time. Because a Node-API binary is ABI-stable across Node versions (the previous lesson), you ship one prebuild per platform/arch and it serves every Node version your users run. A raw-V8/NAN addon, by contrast, needs a prebuild per platform per Node ABI version — a combinatorial matrix that balloons your published package and breaks the moment a new Node major ships before you’ve published a matching binary. The --napi flag above is doing exactly that: cutting the prebuild matrix from (platforms × Node versions) down to (platforms). At runtime a loader like node-gyp-build resolves the right prebuild and only falls back to source compilation if none matches.

The alternatives: WASM, a child process, or just JS

Before writing any of that, ask whether you need a native addon at all. Three alternatives sidestep the build problem entirely.

WebAssembly. Compile C, C++, or Rust to a .wasm module and load it with WebAssembly.instantiate. The artifact is a single, portable binary — no per-platform compile, no toolchain at install, the same .wasm runs on every OS and arch. It executes in a sandbox with no ambient access to the filesystem or network; when the code needs syscalls, WASI (the WebAssembly System Interface, exposed via node:wasi) grants them explicitly and capability-scoped. The tradeoffs: data crosses into wasm’s linear memory by copying (you can’t hand it a JS object), and raw OS/C-library integration beyond WASI isn’t available. Excellent for portable compute kernels (parsers, codecs, crypto, image filters); not a path to call an arbitrary OS API.

import { readFile } from "node:fs/promises";
const bytes = await readFile("./resize.wasm");
const { instance } = await WebAssembly.instantiate(bytes);
const out = instance.exports.resize(/* pointers into linear memory */);

Child process to a native binary. If a battle-tested native CLI already exists (ffmpeg, ImageMagick, a Rust tool), spawn it with child_process and talk over stdio or files. The boundary is coarse and the process is isolated: a crash or memory bug in the binary kills the child, not your Node process. The costs are real too — serialization/IPC overhead, you must deploy and version the external binary, and it’s process-per-call unless you pool. Right when the work is already a tool and you value isolation over in-process speed.

Plain JavaScript. Often the honest answer. V8’s JIT is fast; for a great many “we need C for speed” instincts, a careful JS implementation (typed arrays, avoiding allocations in hot loops) is within a small factor and carries zero install risk, zero build matrix, and zero cross-platform variance. The burden of proof is on going native, not on staying in JS.

The decision rule: when NOT to go native

Put it together as a rule you can apply before adding the dependency or writing the code.