How to Handle fsevents in CI Without Linux Install Errors

fsevents is a macOS-only native file watcher used by chokidar/webpack. On Linux CI it is simply skipped - problems arise only when a lockfile or tooling treats it as required.

fsevents is a macOS-only N-API addon for efficient file watching, pulled in transitively by chokidar, webpack, and many dev tools. On Linux it is an optional dependency that npm skips with an unsupported platform notice. CI breaks when something forces it to install or build off macOS.

Why it fails in CI

--omit=optional or a strict installer treats the skipped fsevents as a hard error on Linux.
A lockfile generated on macOS lists fsevents; a non-npm installer tries to build it on Linux → node-gyp failure.
A --frozen-lockfile/--ci mode flags the platform mismatch instead of skipping it.

Install it reliably

Keep optional dependencies enabled and let the installer skip fsevents on Linux - it is genuinely macOS-only and watchers fall back to polling/inotify. Do not add it to dependencies or force a build.

Terminal

# Linux/Windows CI: optional deps enabled - fsevents is skipped, not built
npm ci

# the "npm warn ... unsupported platform for fsevents@x" line is expected on Linux
# do NOT npm ci --omit=optional if a tool expects fsevents to resolve as optional

Cache & speed

Cache ~/.npm keyed on lockfile + runner OS. Because fsevents resolves differently per platform, key any node_modules cache on runner.os so a macOS leg’s fsevents is never reused on Linux.

.github/workflows/ci.yml

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

Common errors

npm warn ... unsupported platform for fsevents on Linux → expected; not an error.
gyp ERR! building fsevents on Linux → a non-npm installer is forcing it; use npm/pnpm/yarn that honor os constraints.
Install fails after --omit=optional → a tool needed fsevents to resolve as optional; drop the flag.

Key takeaways

fsevents is macOS-only and lives in optionalDependencies by design.
Keep optional deps enabled; the Linux "unsupported platform" warning is expected.
Key caches on runner.os so a macOS fsevents is never reused on Linux.