npm / gatsby

gatsby

What changed in gatsby 3 to 5, from its official release notes, upgrade guides and advisories. Sources checked 2026-11-14.

71 breaking7 deprecations14 new APIs and options4 performance13 behavior and defaults3 tooling5 fixes and other

See which of these apply to your code, ranked, in your agent:

npx @unstale/cli init

@unstale/cli 0.3.1 on npm

gatsby 519 changes

Breaking changes 6

Gatsby Partial Hydration is incompatible with React 19; users relying on it should not upgrade to React 19.
5.16.0release notes
Gatsby 2 and Gatsby 3 are no longer officially supported as of Gatsby 5.
5.0.0upgrade guide
Gatsby 5 drops support for Node 14 and 16 and moves to Node 18.
5.0.0upgrade guide release notes
Non-ESM browsers are no longer polyfilled by default, speeding up production JavaScript and CSS bundle builds.
5.0.0upgrade guide
React 18 is the new minimum required version; official support for React 16 and 17 is dropped.
5.0.0upgrade guide
React 18 is listed as a major dependency update.
5.0.0release notes

New APIs and options 6

Export this callback from gatsby-browser.js to handle errors caught by error boundaries in React 19.
5.16.0release notes
Export this callback from gatsby-browser.js to handle uncaught errors in React 19.
5.16.0release notes
The createSlice action in the createPages API defines shared components that Gatsby can build once and stitch into pages, reducing rebuilds when those components change.
5.0.0upgrade guide
Partial Hydration (Beta) lets developers selectively add interactivity to an otherwise static app; it is opt-in and requires experimental react and react-dom versions.
5.0.0upgrade guide
The Slice placeholder replaces a shared component in a page so Gatsby can stitch in its separately built markup and JavaScript.
5.0.0upgrade guide
Add the use client directive to components that need to be client components when using Partial Hydration.
5.0.0upgrade guide

Performance 2

Changes to sort and aggregation fields reduce resource usage, significantly reduce memory usage, and speed up the “Building schema” step.
5.0.0upgrade guide
This release includes performance improvements.
5.0.0release notes

Behavior and default changes 3

React 19's document metadata hoisting feature is disabled in Gatsby because it conflicts with the Gatsby Head API.
5.16.0release notes
Gatsby now officially supports Node.js 24.
5.16.0release notes
Gatsby and Gatsby-maintained packages officially support React 19; existing stable functionality is intended to work, and React 18 remains supported.
5.16.0release notes

Tooling 1

Gatsby updates its integrated GraphQL development environment to GraphiQL v2, bringing dark mode, tabs, persisted state, improved documentation search and markdown support, and a plugin ecosystem.
5.0.0upgrade guide

Fixes and other changes 1

Fixes regressions in the Gatsby Head API, including cases where <title> did not update document.title.
5.16.1release notes

gatsby 444 changes

Breaking changes 28

For DSG and SSR, external files required through fs in specified lifecycle APIs are not included in bundles; move their contents to an imported JS/TS file.
4.0.0upgrade guide
Gatsby 4 with LMDB no longer supports circular references in data.
4.0.0upgrade guide
Pass the full node to deleteNode instead of a string node ID.
3.0.0, 4.0.0upgrade guide upgrade guide
Remove this gatsby-config flag; the feature is part of Gatsby core and can no longer be enabled or disabled with the flag.
4.0.0upgrade guide
Remove this gatsby-config flag; the feature is part of Gatsby core and can no longer be enabled or disabled with the flag.
4.0.0upgrade guide
gatsby-admin is no longer available in Gatsby; its experimental activation environment variable is also no longer usable.
4.0.0upgrade guide
This environment variable no longer activates gatsby-admin, which was removed from Gatsby.
4.0.0upgrade guide
The feeds option is now required.
4.0.0upgrade guide
The serialize key inside feeds is now required; define your own serialize function if you previously relied on the default.
4.0.0upgrade guide
The title key inside feeds is now required.
4.0.0upgrade guide
The sizeByPixelDensity option was removed.
4.0.0upgrade guide
The sizeByPixelDensity option was removed.
4.0.0upgrade guide
The sizeByPixelDensity option was removed.
4.0.0upgrade guide
The transformer maps the input id key to jsonId and uses an internally generated UUID for the node id; update GraphQL queries that used id.
4.0.0upgrade guide
The transformer maps the input id key to yamlId and uses an internally generated UUID for the node id; update GraphQL queries that used id.
4.0.0upgrade guide
Use interface inheritance instead of @nodeInterface to implement queryable interfaces.
4.0.0upgrade guide
Remove this gatsby-config flag; the feature is part of Gatsby core and can no longer be enabled or disabled with the flag.
4.0.0upgrade guide
Nodes are persisted after createNode; direct mutations afterward are lost, so use Gatsby actions such as createNodeField.
4.0.0upgrade guide
Gatsby 4 drops support for Node 12; Node.js 14.15.0 or newer is required because lmdb-store requires >=14.15.0.
4.0.0upgrade guide upgrade guide
Interface inheritance replaces @nodeInterface as the way to implement queryable interfaces.
4.0.0upgrade guide
Remove this gatsby-config flag; the feature is part of Gatsby core and can no longer be enabled or disabled with the flag.
4.0.0upgrade guide
This environment variable is removed; pass stage as an option to gatsby-preset-gatsby instead.
4.0.0upgrade guide
Remove this gatsby-config flag; the feature is part of Gatsby core and can no longer be enabled or disabled with the flag.
4.0.0upgrade guide
Run reporter.setErrorMap inside onPluginInit instead of onPreInit.
4.0.0upgrade guide
SitePage now exposes pageContext as JSON rather than inferring individual context fields; queries can no longer select those fields individually.
4.0.0upgrade guide
Schema-related actions can no longer be used in sourceNodes; move them to createSchemaCustomization or use createResolvers.
4.0.0upgrade guide
Pass the full node to touchNode instead of a string node ID.
3.0.0, 4.0.0upgrade guide upgrade guide
Gatsby 4 does not support WSL1 instances because of an upstream lmdb-store issue; the notes recommend updating to WSL2.
4.0.0upgrade guide

Deprecations 4

The ___NODE relation convention is deprecated; @link is the preferred method for defining relations between nodes.
4.0.0upgrade guide
Use findOne as a replacement for runQuery.
4.0.0upgrade guide
nodeModel.getAllNodes is deprecated; use nodeModel.findAll, preferably restricting the number of fetched nodes.
4.0.0upgrade guide
nodeModel.runQuery is deprecated; use nodeModel.findAll and nodeModel.findOne instead.
4.0.0upgrade guide

New APIs and options 6

Gatsby 4 introduces Deferred Static Generation as a new rendering option.
4.0.0upgrade guide upgrade guide
Use findAll as a replacement for runQuery and getAllNodes; it returns an iterable and supports limit and skip.
4.0.0upgrade guide
Use onPluginInit to share initial plugin state with lifecycle APIs; it runs in each worker as it is initialized.
4.0.0upgrade guide
Gatsby 4 introduces Server-Side Rendering as a new rendering option.
4.0.0upgrade guide upgrade guide
The built-in SitePlugin type gains a packageJson field of type JSON.
4.0.0upgrade guide
The built-in SitePlugin type gains a pluginOptions field of type JSON.
4.0.0upgrade guide

Performance 2

The page-renderer size is reduced.
4.0.0upgrade guide
Page queries and static queries can run in parallel, reducing build times by up to 40% for some sites.
4.0.0upgrade guide

Behavior and default changes 3

Do not create nodes in custom resolvers; create nodes in sourceNodes instead.
4.0.0upgrade guide
The WordPress source plugin uses gatsby-plugin-image.
4.0.0upgrade guide
A queue was added to prefetching, making it less eager.
4.0.0upgrade guide

Tooling 1

The build output now identifies pages as SSG, DSG, SSR, or a Gatsby Function.
4.0.0upgrade guide

gatsby 354 changes

Breaking changes 37

The deprecated API is removed; rename its instances to actions to keep the same behavior.
3.0.0upgrade guide
Types with disabled inference must explicitly declare a parent-child relationship to provide child fields.
3.0.0upgrade guide
The many argument is no longer needed for the childOf directive.
3.0.0upgrade guide
The fieldName and fieldValue arguments are removed; use name and value instead.
3.0.0upgrade guide
CSS Modules are imported as ES Modules, for example by importing named class exports from the module stylesheet.
3.0.0upgrade guide
The deprecated API is removed; iterate over the nodes and call deleteNode instead.
3.0.0upgrade guide
Gatsby upgrades ESLint from version 6 to version 7; sites with custom ESLint configuration should check the migration guide.
3.0.0upgrade guide
Gatsby replaces eslint-loader with eslint-webpack-plugin; warnings and errors are displayed later than in version 2.
3.0.0upgrade guide
The deprecated key is removed from gatsby-config.js; define Gatsby themes inside the plugins array instead.
3.0.0upgrade guide
A new gatsby-core-utils utility supersedes file download utilities from gatsby-source-filesystem.
3.0.0upgrade guide
File assets such as fonts and PDFs are handled as ES Modules; replace require functions with imports.
3.0.0upgrade guide
If Gatsby discovers fs modules are used, it disables incremental-build mode as a safety measure.
3.0.0upgrade guide
A new plugin is required for Gatsby Cloud Hosting; it generates redirects and rewrites for client-side routes and supports custom per-file headers.
3.0.0upgrade guide
The plugin is deprecated and is not compatible with Gatsby v3.
3.0.0upgrade guide
A new image plugin replaces gatsby-image and provides a simplified GraphQL API and the StaticImage component.
3.0.0upgrade guide
When using tableOfContents, absolute now defaults to false.
3.0.0upgrade guide
When using tableOfContents, pathToSlugField now defaults to an empty string.
3.0.0upgrade guide
This gatsby-browser API is removed; use loadPage instead.
3.0.0upgrade guide
This gatsby-browser API is removed; use loadPageSync instead.
3.0.0upgrade guide
Queries can no longer use the global tag without importing it; import graphql from Gatsby.
3.0.0upgrade guide
This API is removed from the public API surface because Gatsby now checks internally whether a node has changed.
3.0.0upgrade guide
The deprecated gatsby-link API is removed; use navigate instead.
3.0.0upgrade guide
The minimum required Node.js version is 12.13.0; Node 10 is no longer supported.
3.0.0upgrade guide upgrade guide release notes
Remove this argument from inference directives.
3.0.0upgrade guide
With firstOnly: false or unset, no results now return an empty array instead of null.
3.0.0upgrade guide
The deprecated API is removed; rename its instances to pageContext.
3.0.0upgrade guide
Replace process.browser checks in components with a check for whether window is undefined.
3.0.0upgrade guide
The deprecated gatsby-link API is removed; use navigate instead.
3.0.0upgrade guide
Gatsby is compatible with React 17, and its minimum React version is now 16.9.0 to support Fast Refresh, Hooks, and Suspense by default.
3.0.0upgrade guide
GraphQL regex filters require backslashes to be escaped once instead of twice.
3.0.0upgrade guide
The deprecated gatsby-link API is removed; use navigate instead.
3.0.0upgrade guide
This gatsby-browser API is removed; use wrapPageElement instead.
3.0.0upgrade guide
When defining a field of complex type, explicitly assign the corresponding extension or a custom resolver.
3.0.0upgrade guide
ScrollContainer has been removed; use the useScrollRestoration hook instead.
3.0.0upgrade guide
Queries for abstract types must request __typename explicitly; Gatsby no longer adds it automatically.
3.0.0upgrade guide
Gatsby upgrades webpack from version 4 to version 5, which can require changes for Gatsby plugins and webpack plugins.
3.0.0upgrade guide upgrade guide
webpack no longer automatically polyfills Node APIs such as path and fs in the browser; configure them manually.
3.0.0upgrade guide

Deprecations 3

Passing node as a named argument is deprecated in favor of passing the full node to the function.
3.0.0upgrade guide
The directive is deprecated in favor of interface inheritance.
3.0.0upgrade guide upgrade guide
Passing nodeId as a named argument is deprecated in favor of passing the full node.
3.0.0upgrade guide

New APIs and options 2

Accepts reactImportSource and passes it to @babel/preset-react's importSource field; it is supported only when reactRuntime is automatic.
3.0.0upgrade guide
The plugin now supports the topLevelImportPaths option.
3.0.0upgrade guide

Behavior and default changes 7

Keep the .cache and public directories from previous builds to use incremental builds.
3.0.0upgrade guide
Fast Refresh is the default overlay, replacing react-hot-loader and preserving state across re-renders while improving error handling.
3.0.0upgrade guide
gatsby-plugin-image reaches its 1.0.0 release.
3.0.0release notes
The plugin adds retries when downloading assets and on network errors, and supports gatsby-plugin-image.
3.0.0upgrade guide
Gatsby now displays GraphQL deprecations as CLI warnings.
3.0.0upgrade guide
Gatsby introduces incremental HTML builds that track inputs used to generate HTML; using fs in gatsby-ssr.js disables this feature.
3.0.0upgrade guide upgrade guide
JSON modules allow importing only the default export; importing sub-properties produces a warning.
3.0.0upgrade guide

Tooling 1

The default ESLint configuration adds rules warning against anonymous default exports and page templates with more than one default export.
3.0.0upgrade guide

Fixes and other changes 4

The plugin now validates its options.
3.0.0upgrade guide
Fixes an HTML field gatsby-image regression that prevented image transforms in certain situations.
3.0.0upgrade guide
AVIF images are now cached.
3.0.0upgrade guide
Page invalidations are no longer missed when runQuery is used in custom resolvers.
3.0.0upgrade guide