How to Install classic-level / leveldown in CI

classic-level (the successor to leveldown) bundles LevelDB and compiles a C++ addon. Prebuilds cover common platforms; Alpine/musl falls back to a source build.

classic-level and the older leveldown ship prebuilt N-API binaries via prebuildify for common platforms and bundle the LevelDB C++ source. A missing prebuilt - Alpine/musl, new Node major, unusual arch - forces a node-gyp source build.

Why it fails in CI

Alpine/musl has no prebuilt → C++ source build needs python3 + g++ + make.
A new Node major or uncommon arch lacks a prebuilt → source build.
A node_modules cached under another Node ABI carries an incompatible .node.

Install it reliably

On common Linux a clean install pulls the prebuilt. On Alpine or a forced source build, provide the C++ toolchain; LevelDB is bundled so no system library is needed.

Terminal

# common platforms: prebuilt binary
npm ci

# Alpine / source build
apk add --no-cache python3 make g++
npm install classic-level --build-from-source

# after a Node version change, rebuild the addon
npm rebuild classic-level

Cache & speed

Cache ~/.npm keyed on lockfile + Node version. The LevelDB compile is slow, so prefer a prebuilt-supported platform or bake the toolchain into the 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

prebuild-install warn install No prebuilt binaries found → install python3 + g++ for the source build.
NODE_MODULE_VERSION mismatch → npm rebuild classic-level on the target Node.
g++: command not found → install g++/build-essential.

Key takeaways

classic-level bundles LevelDB and ships prebuilds; Alpine/musl needs a C++ build.
Provide python3 + g++ for the source build; rebuild after Node changes.
Prefer classic-level over the deprecated leveldown.