Installing Gatsby onto an M1 MacBook Air

Back in November, Apple announced their new, in‑house processor chip: the M1.

Now, four months later, this new silicon is starting to make its way into the hands of the public, mine arrived just days ago!

As is almost always the case, there are a few minor teething problems that need addressing in setting your development environment up on all‑new architecture. It's very reminiscent of trying to install Windows onto my first AMD64 machine.

The biggest issue I hit with Gatsby in March 2021 was its reliance on sharp, which could not compile under Apple Silicon M1 ARM64 in my setup.

Setting up from a blank slate and avoiding these pitfalls ‑ however ‑ is fairly straightforward.

Install Xcode

First things first, install Xcode for all the good Apple development tools it includes (including git). You can either do this via the App Store or ‑ if you have an Apple Developer account ‑ download an installable directly from Apple.

A minor point: I found the installation process took much longer than expected. I'd advise against progressing any further in these steps until Xcode is fully installed.

Install Homebrew

Without Homebrew, I feel you might struggle. Fortunately, it takes seconds to install from the Terminal:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install Nvm

In that 2021 setup, my Gatsby installation kept trying to revert to Node.js 14. I used NVM to control Node.js versions. Homebrew was another option, but with the Apple Silicon compatibility issues I was seeing then, I preferred the finite control NVM gave me over which version ran, and where.

If you're running the default (zsh) shell, NVM is going to look for your profile in ~/.zshrc, which doesn't exist by default. So, if you're on a new, clean installation, you're going to want to create that file first:

touch ~/.zshrc

And then install NVM:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash

Install Node.js

With NVM installed, I used Node.js 15.14.0, which worked in that M1 environment:

nvm i 15.14.0

If you want to set a specific global, default version of Node.js, you can do so like this:

nvm alias default 15.14.0

The 2021 vips Workaround

This was where sharp fell over under M1 in my 2021 setup. Installing vips provided an ARM64‑compatible libvips installation that sharp could use when the Gatsby dependencies were installed.

This was one of the reasons I installed Homebrew above. The command I used was:

brew install vips

This will probably take a while. Let it run.

Install Yarn

Yarn is my package manager of choice. You may alternatively be using NPM or even Bower, so by all means swap out the following commands for your preferred package manager. From here on out it should be a very familiar process anyway.

Using Homebrew again:

brew install yarn

Or alternatively, there is also a shell script you can also paste into Terminal:

curl -o- -L https://yarnpkg.com/install.sh | bash

Install the Gatsby CLI

This isn't a totally necessary step, but if you want to use the Gatsby CLI, for example, to set up new projects via gatsby new, then now is the time to install it:

yarn global add gatsby-cli

If you prefer not to install it globally, you can also install it locally via yarn add gatsby-cli, although you will also then need to prefix your gatsby commands with yarn. For example: yarn gatsby develop.

Get Back to Developing.

With all that in place, I could pull down an existing Gatsby project or set up a new one.

Remove Any Existing Modules And/Or Caches

If you have an existing project that you've already tried to run and failed, then the first step is to remove your existing modules and caches. From your project root:

rm -rf node_modules .cache public

This will remove the node_modules, .cache, and public folders.

Reinstall Dependencies

This is as simple as:

yarn

At the time, this reinstalled the dependencies and let sharp use the ARM64‑compatible libvips installation.

Code!

I could then spool the project up via yarn gatsby develop.