How to Upgrade Gatsby to Version 4

To upgrade Gatsby to the next major version you have to update your project dependencies. Before you do that, make sure you have backed up a working version of your project. Use Git version control or at least make a copy.

Although this guide uses Gatsby v3 to update to version 4, you should be able to upgrade the same way from Gatsby v2 to v4.

Updating to the Latest Current Version

First step is to update dependencies to their latest available version within your current Gatsby version. You can run npm outdated command to see which version you can update to.

npm outdated
Package   Current   Wanted   Latest   Location              Depended by
gatsby    3.5.0     3.14.6   4.11.1   node_modules/gatsby   your-project

You should also see other dependencies in this list, like Gatsby plugins. The wanted version is the one you should update to before you jump to version 4.

To update dependencies to their wanted versions, run npm update.

After completing the update, npm outdated should output Gatsby and its plugins in their wanted version.

npm outdated
Package   Current   Wanted   Latest   Location              Depended by
gatsby    3.14.6    3.14.6   4.11.1   node_modules/gatsby   your-project

Updating to Version 4

Start by updating Gatsby to version 4 by running npm install gatsby@latest. If you are using NPM version 7, you might need to use npm install gatsby@latest --legacy-peer-deps instead.

npm install gatsby@latest

You can check your NPM version by running npm -v command.

npm -v
8.3.1

Finally, update every Gatsby plugin to its latest version. Look for dependencies inside package.json that start with gatsby- and update each one by running npm install gatsby-package-name@latest.

For example, if you have gatsby-plugin-sass plugin as a dependency, run the following command.

npm install gatsby-plugin-sass@latest

After updating Gatsby and all its plugins to their latest versions, run npm outdated again. If it doesn’t show any Gatsby dependencies, then you have successfully updated to the latest version.

Updating Node Version on Netlify

If you are hosting your Gatsby site on Netlify, you might need to configure your site to use a newer Node.

My site was tied to Node.js v12.18.0, but Gatsby 4 requires Node.js v14.15.0. Netlify would throw an error and fail the build.

Gatsby requires Node.js 14.15.0 or higher (you have v12.18.0)

To solve this issue, you need to navigate to your Site settings on Netlify. Go into Build & deploy section and look under Environment. You should see Environment variables that you can edit. Add a new one and set its key to NODE_VERSION and value to 14.15.0. Even better, set it to whichever is the current LTS version.

Now redeploy your website and Netlify should successfully build with Gatsby v4.

Conclusion

Be careful with updating React to the latest version, although it shows up in npm outdated. Updating it might break some Gatsby plugins.

I updated to React 18, which broke Netlify CMS, so I had to revert to React 17 to fix that.

If you run into errors when running your project, check out the official migration guide. You might need to refactor some of your existing code.