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:
- Versions of
fsevents
below 1.2.9 aren’t compatible with Node v12+ - The tool
fsevents
uses to compile (node-gyp
) has issues with compiling on macOS Catalina - 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.