Migrate to Netlify Today

Netlify announces the next evolution of Gatsby Cloud. Learn more

v5 Release Notes

Welcome to gatsby@5.0.0 release (November 2022 #1).

Gatsby 5 introduces the Slices API and Partial Hydration (Beta). Slices unlock up to 90% reduction in build duration for content changes in highly shared components, Partial Hydration allows you to ship only the necessary JavaScript to the browser. We’ve tried to make migration smooth. Please refer to the migration guide and let us know if you encounter any issues when migrating.

Key highlights of this release:

  • Slice API - Only re-build individual slices of your page
  • Partial Hydration (Beta) - Improve frontend performance by shipping less JavaScript
  • GraphiQL v2 - An all new UI with features like dark mode, tabs, and persisted state

Major dependency updates:

Bleeding Edge: Want to try new features as soon as possible? Install gatsby@next and let us know if you have any issues.

Full changelog

Breaking Changes

If you’re looking for an overview of all breaking changes and how to migrate, please see the migrating from v4 to v5 guide.

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.

Overview Video

Prefer video over text? No problem! Learn more about all the new features in the video below:

Slice API

The Slice API allows you to define highly-shared components in your site, which will then inform Gatsby to build those shared components only once. After the files are built, Gatsby will then stitch the resulting markup and JavaScript to the pages that include that shared component. This means that changes to highly-shared components (such as headers, footers, and common layouts) no longer require a rebuild of all pages that use that shared component.

The Slice API introduces two critical pieces, the createSlice action from the createPages API and the <Slice> placeholder. To create a Slice, you must first call createSlice within gatsby-node:

Then, use the <Slice> placeholder where the <Header> component was previously:

Here’s an overview of how it works:

Diagram of building a header with Gatsby Slice

Now, when a code update or data update is made for the <Header> component, only the HTML for the Slice will be updated, and later stitched into the pre-existing HTML for the pages that use it.

We want to make sure the Slice API is worthwhile for all Gatsby sites, so the implementation is built into Gatsby’s open source product. To validate the improvements of the Slice API, we created a 10,000 page Contentful site with a shared header. We then benchmarked two types of changes, code updates to the git repository and data updates to Contentful. Here are the results:

Code UpdateData Update
No Slices (Self-Hosted)1253s1276s
With Slices (Self-Hosted)1011s958s
No Slices on Gatsby Cloud155s22s
With Slices on Gatsby Cloud129s15s
With Slices on Gatsby Cloud + Optimizations34s10s

Across the board we can see at least a 20% decrease in build time when using Slices. When using the Slices Optimization on Gatsby Cloud, build time decreases by 78% for code updates compared to No Slices on Gatsby Cloud. As the site grows, the benefit of the Gatsby Slice API will only increase.

For more information, read the Using Slices How-To Guide or the Slice API Reference Documentation.

If you have any questions about the Slice API, you can comment on the Gatsby 5 Umbrella Discussion or gatsby-5 Discord channel.

Partial Hydration (Beta)

Partial Hydration enables you to selectively add interactivity to your otherwise completly static app. This results in improved frontend performance while keeping the benefits of client-side apps. Gatsby uses React server components to achieve this.

Hydration (or often referred to as re-hydration) is the process of using client-side JavaScript to add application state and interactivity to server-rendered HTML. Since the initial release of Gatsby, apps built with Gatsby were always fully hydrated on the client. With Gatsby 5 you now can also use Partial Hydration inside Gatsby. Here’s a visualization showing how Full Hydration and Partial Hydration differ conceptually:

Two stylized browser windows on the left and right side. The left one has the title "Full Hydration", the right one "Partial Hydration". Both browser windows have a stylized web page (with header, content, footer, etc.) with mostly static content except for an interactive gallery. The left window has its complete window marked blue (as the full page hydrates), the right one only the interactive gallery (because of Partial Hydration).

Partial Hydration is in Beta and not enabled by default. You have to opt-in to try it out. The reason for this is that React server components are still quite new (the ecosystem as a whole hasn’t caught up, e.g. CSS-in-JS libraries) and you are currently required to use an experimental version of react/react-dom. Therefore we don’t recommend using Partial Hydration in production just yet. Once things have stabilized we’ll announce the general availablity release of Partial Hydration and adjust the documentation.

Read the Partial Hydration How-To Guide for detailed instructions. We also recommend reading the Partial Hydration Conceptual Guide to understand why Gatsby chose React server components and how Partial Hydration works on a high-level.

As a quick start, here’s how you can use Partial Hydration in Gatsby 5 today:

  • Install experimental version of react and react-dom:
  • Enable the feature flag inside gatsby-config:
  • Add the "use client" directive to any component that needs to be a client component. You can see an example in the gatsby-partial-hydration-starter

If you have any questions about Partial Hydration, you can comment on the RFC: Partial Hydration or partial-hydration Discord channel.

GraphiQL v2

GraphiQL is Gatsby’s integrated GraphQL development environment (IDE). It’s a powerful (and all-around awesome) tool you’ll use often while building Gatsby websites. We’ve updated GraphiQL from v1 to v2 to bring you these cool new features:

  • Dark Mode
  • Tabs
  • Persisted State/Tabs using localStorage
  • Better documentation explorer through search and markdown support
  • Plugin ecosystem

Want to learn more? Head to the Introducing GraphiQL docs.

The plugin ecosystem also will allow us to more easily add functionality to GraphiQL in the future. In preparation for this release we’ve created @graphiql/plugin-code-exporter for example.

Many thanks go to acao and the Stellate team for shipping GraphiQL v2! More props in this tweet thread.

Node 18

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.

React 18

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.

Performance improvements

Highlights from v4

While we have your attention we want to showcase all the awesome features we shipped during the Gatsby 4 lifecycle. Give them a try!

  • Script Component: Gatsby’s Script component offers a convenient way to declare different loading strategies, and a default loading strategy that gives Gatsby users strong performance out of the box.
  • Head API: Gatsby includes a built-in Head export that allows you to add elements to the document head of your pages. Compared to react-helmet or other similar solutions, Gatsby Head is easier to use, more performant, has a smaller bundle size, and supports the latest React features.
  • MDX v2: gatsby-plugin-mdx was updated to support MDX v2. All of the speed, bundle size, and syntax improvements for MDX v2 can be taken advantage of in Gatsby.
  • TypeScript & GraphQL Typegen: You can write your gatsby-config and gatsby-node in TypeScript now. Together with GraphQL Typegen which automatically generates TypeScript types for your GraphQL queries you can author all your Gatsby code in TypeScript.
  • Image CDN: Images are typically the largest files on a site and delay page load significantly while they are pulled over the network. With Image CDN, image processing can be done outside of your builds so you can ship your content even faster.


A big Thank You to our community who contributed to this release 💜

Start building today on Netlify!
Edit this page on GitHub
© 2023 Gatsby, Inc.