sharp Install Failure

Symptom

npm install -g @testmuai/kane-cli fails with:

npm error sharp: Attempting to build from source via node-gyp
npm error sharp: Please add node-addon-api to your dependencies

This can happen on any Node version (18, 20, 22, 26) and any platform (macOS, Linux, Windows).

sharp is an optional dependency of Kane CLI, so the install succeeds even if sharp fails. Screenshots then upload as PNG instead of WebP (~30% larger, with no functional impact). Requires Kane CLI 0.3.4 or later. To upgrade, run npm install -g @testmuai/kane-cli@latest.

Root cause

Kane CLI uses sharp to compress screenshots from PNG to WebP during upload. This compression is optional. sharp 0.34 and later deliver the native binary through platform-specific optional packages (@img/sharp-darwin-arm64, etc.). When sharp cannot load its prebuilt binary, it tries to build from source instead. That build fails because node-addon-api is not present. The three most common triggers, from most to least likely:

1. System libvips detected (macOS, most common)

sharp’s install/check.js runs pkg-config --modversion vips-cpp. If it finds a system-wide libvips, it skips the bundled prebuilt binary and tries to compile against the system copy. That always leads to the source-build failure. How libvips gets on your system: several Homebrew formulas install it as a dependency, so you probably did not install it yourself. The most common sources:

brew install appium: Appium depends on vips for image processing
brew install imagemagick: pulls vips as a dependency on some configurations
brew install gdal, brew install inkscape: other graphics-heavy formulas

Diagnosis:

# Is libvips installed?
pkg-config --modversion vips-cpp
# If this prints a version (e.g. 8.18.2), that's the cause.

# What brew formula pulled it in?
brew uses --installed vips

# When was it installed?
ls -la /opt/homebrew/Cellar/vips/

Fix:

# Option A: bypass libvips detection (recommended)
# You must uninstall first; reinstalling without uninstall won't re-resolve
# sharp because npm considers kane-cli already installed.
npm uninstall -g @testmuai/kane-cli
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g @testmuai/kane-cli

# Make it permanent so future installs/upgrades just work:
echo 'export SHARP_IGNORE_GLOBAL_LIBVIPS=1' >> ~/.zshrc
source ~/.zshrc

# Option B: remove libvips if nothing else needs it
brew uses --installed vips   # check first
brew uninstall vips && brew autoremove

2. npm skipped optional dependencies

sharp lists its platform-specific packages (@img/sharp-darwin-arm64, etc.) under optionalDependencies. If npm is set to skip optional dependencies, the prebuilt binary is never downloaded and sharp tries to build from source. Diagnosis:

npm config get omit          # should NOT contain "optional"
cat ~/.npmrc | grep -i omit  # should be empty
env | grep -i NPM_CONFIG_OMIT

Fix:

# Force optionals for this install
npm uninstall -g @testmuai/kane-cli
npm install -g @testmuai/kane-cli --include=optional

# Or remove the config permanently
npm config delete omit

3. Proxy or firewall blocking @img/* packages

sharp’s prebuilt packages are published under the @img npm scope on the public registry. If a corporate proxy, firewall, or private registry mirror does not forward @img/*, the downloads fail silently (npm does not treat a failed optional download as an error), and sharp tries to build from source. Diagnosis:

# Check if proxy is set
env | grep -iE "proxy|PROXY"

# Try fetching sharp's platform package directly
npm view @img/sharp-darwin-arm64 version

# If ECONNREFUSED on localhost, you have a local proxy that's either
# down or only listening on IPv4 while npm resolves to IPv6 (::1)

Fix: Make sure your proxy or registry mirror forwards the @img scope. If you use a private registry (Artifactory, Verdaccio, GitHub Packages), add a pass-through in your .npmrc:

@img:registry=https://registry.npmjs.org/

Impact when sharp is unavailable

sharp is an optional dependency of Kane CLI. When sharp is not installed:

The install succeeds and does not crash
Screenshots upload as PNG instead of WebP (~30% larger)
Everything else in Kane CLI works normally
No warning is printed (npm hides install script output for global installs)

No action is required if slightly larger screenshot uploads are fine for you. You need the fixes above only if you want WebP compression.

Quick reference

Cause	Diagnosis	Fix
System libvips (macOS)	`pkg-config --modversion vips-cpp`	`export SHARP_IGNORE_GLOBAL_LIBVIPS=1` then uninstall + reinstall
npm skips optionals	`npm config get omit`	`npm config delete omit` then uninstall + reinstall
Proxy blocks @img/*	`npm view @img/sharp-darwin-arm64`	Add `@img` pass-through to proxy/registry
Bleeding-edge Node	`node -v`	Use Node 22 LTS

​Symptom

​Root cause

​1. System libvips detected (macOS, most common)

​2. npm skipped optional dependencies

​3. Proxy or firewall blocking @img/* packages

​Impact when sharp is unavailable

​Quick reference

Symptom

Root cause

1. System libvips detected (macOS, most common)

2. npm skipped optional dependencies

3. Proxy or firewall blocking @img/* packages

Impact when sharp is unavailable

Quick reference