How to Install sodium-native in CI

sodium-native wraps libsodium as a native addon. CI breaks when no prebuilt binary matches the runner and the bundled source build is missing its toolchain.

sodium-native ships prebuilt binaries via prebuildify for common platforms and bundles libsodium. A platform without a prebuilt - Alpine/musl, unusual arch - falls back to compiling.

Why it fails in CI

Alpine/musl or an uncommon arch has no prebuilt → source build needs python3 + g++ + make.
A node_modules cached under a different Node ABI carries an incompatible binary.
A new Node major may lack a matching prebuilt until the package updates.

Install it reliably

Install fresh on the target platform. Provide the toolchain if a source build is triggered, and rebuild after Node version changes.

Terminal

# common platforms: prebuilt binary, no toolchain
npm ci

# Alpine / source build
apk add --no-cache python3 make g++ libtool autoconf automake
npm install sodium-native --build-from-source

# after a Node version change
npm rebuild sodium-native

Cache & speed

Cache ~/.npm keyed on lockfile + Node version. Source builds of libsodium are slow, so prefer a platform with a prebuilt binary, or bake the toolchain into a custom image.

.github/workflows/ci.yml

- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: npm-${{ runner.os }}-node${{ matrix.node }}-${{ hashFiles('**/package-lock.json') }}

Common errors

No prebuilt binaries found → install the toolchain + autotools for the source build.
NODE_MODULE_VERSION mismatch → npm rebuild sodium-native on the target Node.
autoreconf: command not found → install autoconf automake libtool.

Key takeaways

sodium-native bundles libsodium but a source build still needs a C toolchain + autotools.
Prefer a platform with a prebuilt binary; rebuild after Node changes.
Alpine/musl almost always triggers a source build.