node-gyp "No Xcode or CLT version detected" on macOS CI

node-gyp needs Apple’s Command Line Tools to compile native addons on macOS. On a runner without them - or with a stale CLT receipt - the build aborts before compiling. Often you can avoid compiling entirely.

What this error means

On a macOS runner, installing a package with a native addon fails with No Xcode or CLT version detected! from node-gyp. Linux runs of the same install succeed because they have a toolchain and prebuilt binaries.

node-gyp output

gyp: No Xcode or CLT version detected!
gyp ERR! configure error
gyp ERR! stack Error: `gyp` failed with exit code: 1

Common causes

Command Line Tools missing or stale on the runner

macOS needs the Xcode Command Line Tools for node-gyp. A fresh or updated macOS image without them - or with a broken CLT receipt after an OS bump - fails the configure step.

Building from source when a prebuilt exists

Many native packages ship prebuilt macOS binaries. Forcing a source build (or a missing prebuilt for that arch) drags node-gyp in when it was avoidable.

How to fix it

Prefer a prebuilt binary (avoid compiling)

Most native packages download a prebuilt for the platform when one exists, so node-gyp never runs. Ensure scripts are not disabled and the arch matches.

Terminal

# let prebuilt binaries install (do not pass --ignore-scripts)
npm ci
# Apple Silicon vs Intel: install the matching arch binary

Install the Command Line Tools when you must build

If a source build is unavoidable, ensure the CLT are present on the macOS runner.