Migrating from v4 to v5
Looking for the v4 docs?
Have you run into something that’s not covered here? Add your changes to GitHub!
- Handling Deprecations
- Updating Your Dependencies
- Handling Breaking Changes
- Future Breaking Changes
- For Plugin Maintainers
- Known Issues
Before upgrading to v5 we highly recommend upgrading
gatsby (and all plugins) to the latest v4 version.
Some changes required for Gatsby 5 can be applied incrementally to the latest v4, which should contribute to a smoother upgrade experience.
You can run the
yarn upgrade-interactivecommands in your project to upgrade to the latest v4 release interactively.
After upgrading, run
gatsby build and look for deprecation messages in the build log. Follow instructions to fix those deprecations.
Next, you need to update your dependencies. We recommend upgrading to Node 18 prior to updating your dependencies to ensure that the correct package contents are installed.
You need to update your
package.json to use the
latest version of Gatsby.
Please note: If you use npm 7 or higher you’ll want to use the
--legacy-peer-deps option when following the instructions in this guide. For example, the above command would be:
You need to update your
package.json to use the
latest version of
package.json to use the
latest version for all Gatsby related packages. You should upgrade any package name that starts with
gatsby-*. Note that this only applies to plugins managed in the gatsbyjs/gatsby repository. All packages we manage received a major version bump. Community plugins may not be upgraded yet so please check their repository for the current status.
For example, if you have
gatsby-plugin-image installed in your project, update that package to use the
Using community plugins, you might see warnings like these in your terminal:
If you are using npm 7, the warning may instead be an error:
This is because the plugin needs to update its
peerDependencies to include the new version of Gatsby (see section for plugin maintainers). While this might indicate that the plugin has incompatibilities, in most cases they should continue to work. When using npm 7 or later, you can pass the
--legacy-peer-deps to ignore the warning and install anyway. If your build is failing on Gatsby Cloud, you can add a
.npmrc file with that flag enabled like this:
Please look for already opened issues or PRs on the plugin’s repository to see the status. If you don’t see any, help the maintainers by opening an issue or PR yourself! :)
This section explains breaking changes that were made for Gatsby 5. Some of those changes had a deprecation message in v4. In order to successfully update, you’ll need to resolve these changes.
If you’re curious about our release schedules and which versions are officially supported, head to the Gatsby Framework Version Support document. As of Gatsby 5 we’re no longer supporting Gatsby 2 and Gatsby 3.
We are dropping support for Node 14 and 16 as our currently supported Node 14 version will reach EOL during the Gatsby 5 lifecycle. Since the timing of the “Active LTS” status of Node 18 is nearly the same as Gatsby 5 we’re jumping directly to Node 18. See the main changes in Node 18 release notes.
Check Node’s releases document for version statuses.
We are dropping official support for React 16 and 17. The new minimal required version is React 18. This is a requirement for the Partial Hydration feature.
browserlist configuration changed to now include
supports es6-module by default. This means that Non-ESM browsers (like Internet Explorer) are not polyfilled anymore. If you still need to support those browsers you’ll need to adjust your browserlist configuration.
As per the RFC: Change to sort and aggregation fields API the
sort argument and aggregation’s
field argument were changed from enums to nested input objects. This change enabled lower resource usage and faster “building schema” step.
We provide a codemod (via gatsby-codemods) for you to easily convert your queries to the new syntax. Go to your project and run the following in your terminal:
This will apply the codemod to all your files. If you only want to run it on some files/directories, adjust the last parameter (
npx gatsby-codemods@latest sort-and-aggr-graphql <filepath>).
The old syntax will continue to work as Gatsby automatically applies the mentioned codemod and transforms your code, however we strongly encourage you to permanently migrate your queries to the new syntax. This way you won’t see deprecation messages in your terminal and can be sure that the queries work in GraphiQL (because the old ones won’t).
Examples of syntax before and after the codemod is applied:
In Gatsby 4 the default for the
trailingSlash option was set to
legacy. With Gatsby 5 the
legacy option was removed and the new default is
always. This means that every URL will have a trailing slash. You can configure this option in your
gatsby-config file. We recommend that you explicitly define your desired
trailingSlash behavior. This change will also impact your redirects so make sure that everything is consistent.
We updated our
@gatsbyjs/reach-router fork to be compatible with React 18 and React server components. While doing that we removed the
useNavigate hook. Please use
Throughout the lifecycles of Gatsby 3 & 4 we introduced a couple of feature flags to incrementally ship features to Gatsby. In Gatsby 5 we removed all feature flags and environment variables that are enabled by default. You should remove these flags from your
gatsby-config as they don’t have an effect anymore (you can’t enable or disable them):
GRAPHQL_TYPEGEN(can be enabled through gatsby-config)
Each of these feature flags had a corresponding environment variable (in the format of
process.env.GATSBY_EXPERIMENTAL_%FLAG-NAME%). These environment variables were also removed and don’t have any effect anymore.
The previously unstable API
unstable_shouldOnCreateNode was renamed to
shouldOnCreateNode. It’s considered a stable API now. The functionality is identical, so only a rename will be required.
If you’ve used a similar check inside
onCreateNode as an early return we recommend completely switching to the
shouldOnCreateNode API (and removing the check from
graphql dependency was updated from v15 to v16. In most cases this change will be invisible to you and no action is required. However, if you reached into
gatsby/graphql or are relying on TypeScript types for
graphql v15, you might need to look into the graphql v16 release notes.
Maybe you didn’t know, but Gatsby supported GraphQL Playground as an alternative to GraphiQL for some time now. With Gatsby 5 we’ve updated GraphiQL to v2 which has feature parity with GraphQL Playground. Thus we removed the
GATSBY_GRAPHQL_IDE environment variable and GraphQL Playground. Visit the GraphiQL guide to learn more about GraphiQL v2.
Breaking changes in plugins that we own and maintain.
The default setting for the
output option changed from
/. This means that
sitemap-index.xml will now be created at the root of the site.
gatsby-plugin-mdx now includes
remark-unwrap-images by default. When using
gatsby-remark-images together, the images were placed inside
<p> tags which is invalid HTML (as the images are a combination of
<picture>). We see this as a breaking change as your CSS might depend on this hierarchy.
You can uninstall
remark-unwrap-images from your project if you used it inside the
This section explains deprecations that were made for Gatsby 5. These old behaviors will be removed in v6, at which point they will no longer work. For now, you can still use the old behaviors in v5, but we recommend updating to the new signatures to make future updates easier.
<StaticQuery /> component has been deprecated. Please use
useStaticQuery instead. For more information, see the
<StaticQuery /> will be removed in Gatsby 6.
React 18 introduced stricter hydration errors, thrown when your server-rendered JSX and client-rendered JSX does not match.
Given that these errors can be difficult to debug, we intend to unify as much as possible the props that are passed to your page components during server rendering in Node and client rendering in the browser.
Page props in v6 will consist of:
Effective changes in v6 will include:
pageResourcesprop currently only available in browser context (it’s an internal data structure)
*prop currently only available in server context (in favor of
pathprop that currently differs in server and browser context (in favor of
uriprop in favor of
location prop will remain different in the browser and server context due to the router offering more properties in the browser context from
In the v3 to v4 release notes we mentioned that the
___NODE convention is deprecated. This is still the case for Gatsby 5 since we didn’t get to migrate all important plugins to the new syntax. So this syntax will continue to work in Gatsby 5, but we urge you to migrate to the
@link directive. Get more information.
In most cases, you won’t have to do anything to be v5 compatible. But one thing you can do to be certain your plugin won’t throw any warnings or errors is to set the proper peer dependencies.
Please also note that some of the items inside “Handling Breaking Changes” may also apply to your plugin.
gatsby should be included under
peerDependencies of your plugin and it should specify the proper versions of support.
If your plugin supports both versions:
If you defined the
engines key you’ll also need to update the minimum version:
This section is a work in progress and will be expanded when necessary. It’s a list of known issues you might run into while upgrading Gatsby to v5 and how to solve them.
If you encounter any problem, please let us know in this GitHub discussion.
Since we updated the internal
graphql dependency to v16 you might run into a problem like this:
This error (or any other similar errors) happens when you have multiple versions of
graphql installed in your project. You can check this manually by running:
A brute-force way of solving this is to delete your lock file, delete
node_modules and re-install with
npm install --legacy-peer-deps/
yarn install. This only works though if your project is just
gatsby, if you have a more complicated setup you might need to use features like