# What changed in gatsby

> 110 changes in gatsby 3 to 5 from its official release notes, upgrade guides and advisories: 64 breaking, 7 deprecations, 14 new APIs and options. Each one cited. Sources checked 2026-11-15. HTML: https://unstale.sh/npm/gatsby/

To see which of these apply to a repository, run `npx @unstale/cli init` in it.

## gatsby 5

### Breaking changes

- Gatsby Partial Hydration is incompatible with React 19; users relying on it should not upgrade to React 19. (5.16.0) — [release notes](https://github.com/gatsbyjs/gatsby/releases/tag/gatsby%405.16.0)
- Gatsby 2 and Gatsby 3 are no longer officially supported as of Gatsby 5. (5.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/v5.0/)
- Gatsby 5 drops support for Node 14 and 16 and moves to Node 18. (5.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/v5.0/), [release notes](https://github.com/gatsbyjs/gatsby/releases/tag/gatsby%405.0.0)
- Non-ESM browsers are no longer polyfilled by default, speeding up production JavaScript and CSS bundle builds. (5.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/v5.0/)
- React 18 is the new minimum required version; official support for React 16 and 17 is dropped. (5.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/v5.0/)
- React 18 is listed as a major dependency update. (5.0.0) — [release notes](https://github.com/gatsbyjs/gatsby/releases/tag/gatsby%405.0.0)

### New APIs and options

- Export this callback from gatsby-browser.js to handle errors caught by error boundaries in React 19. (5.16.0) — [release notes](https://github.com/gatsbyjs/gatsby/releases/tag/gatsby%405.16.0)
- Export this callback from gatsby-browser.js to handle uncaught errors in React 19. (5.16.0) — [release notes](https://github.com/gatsbyjs/gatsby/releases/tag/gatsby%405.16.0)
- 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.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/v5.0/)
- 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.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/v5.0/)
- The Slice placeholder replaces a shared component in a page so Gatsby can stitch in its separately built markup and JavaScript. (5.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/v5.0/)
- Add the use client directive to components that need to be client components when using Partial Hydration. (5.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/v5.0/)

### Performance

- Changes to sort and aggregation fields reduce resource usage, significantly reduce memory usage, and speed up the “Building schema” step. (5.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/v5.0/)
- This release includes performance improvements. (5.0.0) — [release notes](https://github.com/gatsbyjs/gatsby/releases/tag/gatsby%405.0.0)

### Behavior and default changes

- React 19's document metadata hoisting feature is disabled in Gatsby because it conflicts with the Gatsby Head API. (5.16.0) — [release notes](https://github.com/gatsbyjs/gatsby/releases/tag/gatsby%405.16.0)
- Gatsby now officially supports Node.js 24. (5.16.0) — [release notes](https://github.com/gatsbyjs/gatsby/releases/tag/gatsby%405.16.0)
- Gatsby and Gatsby-maintained packages officially support React 19; existing stable functionality is intended to work, and React 18 remains supported. (5.16.0) — [release notes](https://github.com/gatsbyjs/gatsby/releases/tag/gatsby%405.16.0)

### Tooling

- 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.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/v5.0/)

### Fixes and other changes

- Fixes regressions in the Gatsby Head API, including cases where <title> did not update document.title. (5.16.1) — [release notes](https://github.com/gatsbyjs/gatsby/releases/tag/gatsby%405.16.1)

## gatsby 4

### Breaking changes

- 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.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/)
- Gatsby 4 with LMDB no longer supports circular references in data. (4.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/)
- Pass the full node to `deleteNode` instead of a string node ID. (3.0.0, 4.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v2-to-v3/), [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/)
- gatsby-admin is no longer available in Gatsby; its experimental activation environment variable is also no longer usable. (4.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/)
- This environment variable no longer activates gatsby-admin, which was removed from Gatsby. (4.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/)
- The feeds option is now required. (4.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/)
- The serialize key inside feeds is now required; define your own serialize function if you previously relied on the default. (4.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/)
- The title key inside feeds is now required. (4.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/)
- The sizeByPixelDensity option was removed. (4.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/)
- 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.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/)
- 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.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/)
- Use interface inheritance instead of @nodeInterface to implement queryable interfaces. (4.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/)
- Nodes are persisted after createNode; direct mutations afterward are lost, so use Gatsby actions such as createNodeField. (4.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/)
- 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.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/), [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/v4.0/)
- Interface inheritance replaces @nodeInterface as the way to implement queryable interfaces. (4.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/)
- This environment variable is removed; pass stage as an option to gatsby-preset-gatsby instead. (4.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/)
- 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.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/)
- Run reporter.setErrorMap inside onPluginInit instead of onPreInit. (4.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/)
- SitePage now exposes pageContext as JSON rather than inferring individual context fields; queries can no longer select those fields individually. (4.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/)
- Schema-related actions can no longer be used in sourceNodes; move them to createSchemaCustomization or use createResolvers. (4.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/)
- Pass the full node to `touchNode` instead of a string node ID. (3.0.0, 4.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v2-to-v3/), [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/)
- Gatsby 4 does not support WSL1 instances because of an upstream lmdb-store issue; the notes recommend updating to WSL2. (4.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/)

### Deprecations

- The ___NODE relation convention is deprecated; @link is the preferred method for defining relations between nodes. (4.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/)
- Use findOne as a replacement for runQuery. (4.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/)
- nodeModel.getAllNodes is deprecated; use nodeModel.findAll, preferably restricting the number of fetched nodes. (4.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/)
- nodeModel.runQuery is deprecated; use nodeModel.findAll and nodeModel.findOne instead. (4.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/)

### New APIs and options

- Gatsby 4 introduces Deferred Static Generation as a new rendering option. (4.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/), [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/v4.0/)
- Use findAll as a replacement for runQuery and getAllNodes; it returns an iterable and supports limit and skip. (4.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/)
- Use onPluginInit to share initial plugin state with lifecycle APIs; it runs in each worker as it is initialized. (4.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/)
- Gatsby 4 introduces Server-Side Rendering as a new rendering option. (4.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/), [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/v4.0/)
- The built-in SitePlugin type gains a packageJson field of type JSON. (4.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/)
- The built-in SitePlugin type gains a pluginOptions field of type JSON. (4.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/)

### Performance

- The page-renderer size is reduced. (4.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/v4.0/)
- Page queries and static queries can run in parallel, reducing build times by up to 40% for some sites. (4.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/v4.0/)

### Behavior and default changes

- Do not create nodes in custom resolvers; create nodes in sourceNodes instead. (4.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/)
- The WordPress source plugin uses gatsby-plugin-image. (4.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/v4.0/)
- A queue was added to prefetching, making it less eager. (4.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/v4.0/)

### Tooling

- The build output now identifies pages as SSG, DSG, SSR, or a Gatsby Function. (4.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/v4.0/)

## gatsby 3

### Breaking changes

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

### Deprecations

- Passing `node` as a named argument is deprecated in favor of passing the full node to the function. (3.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v2-to-v3/)
- The directive is deprecated in favor of interface inheritance. (3.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v2-to-v3/), [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/v3.0/)
- Passing `nodeId` as a named argument is deprecated in favor of passing the full node. (3.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v2-to-v3/)

### New APIs and options

- Accepts reactImportSource and passes it to @babel/preset-react's importSource field; it is supported only when reactRuntime is automatic. (3.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/v3.0/)
- The plugin now supports the topLevelImportPaths option. (3.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/v3.0/)

### Behavior and default changes

- Keep the .cache and public directories from previous builds to use incremental builds. (3.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/v3.0/)
- Fast Refresh is the default overlay, replacing react-hot-loader and preserving state across re-renders while improving error handling. (3.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/v3.0/)
- gatsby-plugin-image reaches its 1.0.0 release. (3.0.0) — [release notes](https://github.com/gatsbyjs/gatsby/releases/tag/gatsby%403.0.0)
- The plugin adds retries when downloading assets and on network errors, and supports gatsby-plugin-image. (3.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/v3.0/)
- Gatsby now displays GraphQL deprecations as CLI warnings. (3.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/v3.0/)
- Gatsby introduces incremental HTML builds that track inputs used to generate HTML; using `fs` in gatsby-ssr.js disables this feature. (3.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v2-to-v3/), [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/v3.0/)
- JSON modules allow importing only the default export; importing sub-properties produces a warning. (3.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v2-to-v3/)

### Tooling

- The default ESLint configuration adds rules warning against anonymous default exports and page templates with more than one default export. (3.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/v3.0/)

### Fixes and other changes

- The plugin now validates its options. (3.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/v3.0/)
- Fixes an HTML field gatsby-image regression that prevented image transforms in certain situations. (3.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/v3.0/)
- AVIF images are now cached. (3.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/v3.0/)
- Page invalidations are no longer missed when runQuery is used in custom resolvers. (3.0.0) — [upgrade guide](https://www.gatsbyjs.com/docs/reference/release-notes/v3.0/)