How to Install isolated-vm in CI Without Build Failures

isolated-vm compiles a large C++ addon against V8. With no prebuilt binary for most setups, CI needs a real toolchain and enough memory to finish the compile.

isolated-vm builds a substantial C++ extension via node-gyp that links against the V8 headers shipped with Node. Slim CI images lack the compiler, and small runners can OOM partway through the long compile.

Why it fails in CI

No Python or C++ toolchain on the runner → gyp ERR! find Python / g++: not found.
The V8 C++ compile is heavy; a small runner gets OOM-killed mid-build (exit 137 / Killed).
An old g++/clang lacks the C++17 support the addon needs.

Install it reliably

Provide Python and a modern C++ toolchain, then build. Give the job enough memory headroom because the V8 compile is large.

Terminal

# Debian/Ubuntu: Python + a modern C++ toolchain
apt-get update && apt-get install -y python3 make g++ build-essential

# Alpine
apk add --no-cache python3 make g++ linux-headers

npm ci   # compiles isolated-vm against the Node-bundled V8 headers

Cache & speed

Cache ~/.npm and ~/.cache/node-gyp (downloaded Node headers) keyed on the Node version. The compile dominates install time, so a bigger runner finishes faster and avoids OOM retries.

.github/workflows/ci.yml

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

Common errors

Killed / exit 137 during the compile → OOM on a small runner; use a bigger one.
gyp ERR! find Python → install python3.
error: ... requires C++17 → upgrade g++/clang to a modern version.

Key takeaways

isolated-vm compiles a heavy C++ V8 addon - there is rarely a prebuilt to fall back on.
Install Python + a modern C++ toolchain and bake it into the image.
Size the runner for the compile; OOM (exit 137) is the common failure.