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 when it comes to Gatsby is that it relies on sharp, which cannot compile under Apple Silicon M1 ARM64.

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: https://developer.apple.com/download/more/

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

You're going to find that your Gatsby installation keeps trying to revert back to version 14. I use NVM to better control instances of Node.js. You can also use Homebrew to install and manage Node.js but with some slightly odd silicon compatibility issues going on at the moment, I like the finite control NVM offers over which version runs, 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, you can now easily install Node.js. I'm currently running on 15.14.0 which seems to work within the 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

Install vips

This is where Sharp falls over under M1 architecture at present. Installing vips will compile a new version which works, and which will then get picked up by Sharp when you install that as part of your Gatsby project.

This is one of the reasons we installed Homebrew above. To install vips, run:

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 now in place, you can pull down your existing Gatsby project, or set up a new one and ship it.

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

This will install all new dependencies including a recompiled version of Sharp.

Code!

Spool your project up via yarn gatsby develop, and you're away.