How to Install ws Native Addons (bufferutil, utf-8-validate) in CI

By Daniel Zoghalchali·Latchkey

The ws package works in pure JS, but its optional speedups bufferutil and utf-8-validate are native addons that try to compile and can break CI installs.

ws itself is pure JavaScript. It uses two optional native addons - bufferutil and utf-8-validate - that build via node-gyp when present. On a slim image those builds fail, even though ws runs fine without them.

Why it fails in CI

• bufferutil/utf-8-validate trigger a node-gyp build that needs Python + g++; slim images lack both.
• Alpine/musl has no prebuilt for these addons, forcing a source build.
• A node_modules cached from another Node ABI carries an incompatible .node for the addon.

Install it reliably

Either provide the toolchain so the optional addons compile, or skip them - ws falls back to its JavaScript implementation with no functional loss for most workloads.

# Option A: build the optional addons (Debian/Ubuntu)
apt-get update && apt-get install -y python3 make g++ build-essential
npm ci

# Option B: skip the native speedups - ws works without them
npm ci --omit=optional
# or never depend on them: they are optionalDependencies of ws

Cache & speed

Cache ~/.npm keyed on lockfile + Node version. If you keep the addons, also cache ~/.cache/node-gyp. If you omit them, installs are pure-JS-fast with nothing to compile.

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

Common errors

• gyp ERR! building bufferutil/utf-8-validate → install python3 + g++, or omit optional deps.
• NODE_MODULE_VERSION mismatch on the addon → npm rebuild bufferutil utf-8-validate on the target Node.
• Cannot find module 'bufferutil' → only if you explicitly require it; ws does not need it.

Diagnose it: registry, auth, and version resolution

# which registry is actually in effect, and with what credentials?
<pkg-tool> config list 2>/dev/null | grep -iE "registry|auth|token"

# does the exact version resolve from the runner?
<pkg-tool> view <package> versions 2>&1 | tail -3

Key takeaways

• ws is pure JS; bufferutil and utf-8-validate are optional native speedups.
• Install Python + g++ to build them, or --omit=optional to skip the build.
• Skipping the addons does not break ws - it just falls back to JS.

Frequently asked questions

Related guides

References

• GitHub Actions documentation