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.
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
After completing the update,
npm outdated should output Gatsby and its plugins in their
npm outdated Package Current Wanted Latest Location Depended by gatsby 3.14.6 3.14.6 4.11.1 node_modules/gatsby your-project
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.
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.
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.