Fixing installation fsevents install errors when using Gatsby

If you’re using Gatsby, you might have noticed a rather lengthy, unhelpful message in your terminal when you run yarn install or yarn add that relates to fsevents. While Yarn will tell you this is okay because the dependency is “optional”, it’s really not.

Running Gatsby on macOS without fsevents installed will result in much higher CPU usage (worse battery life) and slower refresh performance in your browser. So while technically it is optional, it’s really in your best interest to get fsevents installed.

So what’s the issue? #

Without getting too into the weeds, there are a few issues causing this:

1. Versions of fsevents below 1.2.9 aren’t compatible with Node v12+
2. The tool fsevents uses to compile (node-gyp) has issues with compiling on macOS Catalina
3. Compatible versions of fsevents above 1.2.9 aren’t available as binaries

Two short, sweet fixes: #

Option 1: Force upgrade chokidar #

Gatsby doesn’t depend on fsevents directly; it depends on a collection of other packages that depend on yet more packages. Follow the list down far enough and you find multiple dependencies on chokidar resolving to the 2.x.x major version. This is the sole package dependent on the 1.x.x version of fsevents, so if we upgrade it to a version with a more recent dependency, we can sidestep the fsevents issue.

To do this, we can use Yarn resolutions. Place this in your package.json and re-run yarn install:

{
  // ...
  “resolutions”: {
    “chokidar”: “^3.4.0”
  }
}

This will result in all dependencies on chokidar being resolved to 3.4.0 or higher. This is unlikely to break your app—despite the major version changing, the most common interfaces are backwards compatible with the 2.x major releases.

Option 2: Require fsevents@1.2.9 #

This uses the same resolutions feature as above, but there’s a caveat: if you run your code on platforms other than macOS that aren’t on a recent version of Yarn, they will fail. This is because earlier versions of Yarn considered resolutions to override the optional nature of a package. Since fsevents only runs on macOS, trying to install it on Linux or Windows is a no-go.

Thankfully, you don’t need to actually commit the change to your package.json because once you run yarn install locally, the resolution gets committed to your yarn.lock file. If someone on your team does a broad yarn upgrade or takes the nuclear option of deleting yarn.lock (which you should almost never do), this change might get blown away. Just be aware of it, or I’ll see you back here in a few months.

{
  // ...
  “resolutions”: {
    “fsevents”: “1.2.9”
  }
}

Parting Words #

If neither of these work for you or if you have a better solution, please reach out and let me know. You can follow me on Twitter here; my DMs are open.