v5 Release Notes
firstname.lastname@example.org release (November 2022 #1).
Key highlights of this release:
- Slice API - Only re-build individual slices of your page
- 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.
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.
Prefer video over text? No problem! Learn more about all the new features in the video below:
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
Then, use the
<Slice> placeholder where the
<Header> component was previously:
Here’s an overview of how it works:
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 Update||Data Update|
|No Slices (Self-Hosted)||1253s||1276s|
|With Slices (Self-Hosted)||1011s||958s|
|No Slices on Gatsby Cloud||155s||22s|
|With Slices on Gatsby Cloud||129s||15s|
|With Slices on Gatsby Cloud + Optimizations||34s||10s|
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.
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-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
- Enable the feature flag inside
- 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 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
- Persisted State/Tabs using
- 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.
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.
The GraphQL schema: Changes to sort and aggregation fields change enables lower resource usage (significantly reduced memory usage) and faster “Building schema” step.
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
Headexport 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-mdxwas 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-nodein 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 💜
- mattmuroya: chore(gatsby-source-contentful): Correct image embed code sample PR #36670
- yasell: fix(gatsby): remove unused console.log PR #36713
- ashhitch: chore(docs): Update storybook main.js examples to be consistant PR #36702
- joshterrill: chore: Update old placehold.it URLs PR #36731
- Toxillo: chore(docs): Update tutorial part 5 with a better fitting screenshot PR #36741
- ShaunDychko: chore(gatsby-plugin-sitemap): Document
excludesglob matching PR #36690
- Lightwight: fix(gatsby-page-utils): path creation on windows filesystem PR #36766
- kentmz: chore(docs): added Dialoguewise to headless cms list PR #36651
- brysongilbert: chore(gatsby-core-utils): Update README with correct cpuCoreCount args PR #36838
- mac2000: feat(gatsby-remark-embed-snippet): added csproj to language map so it will be recognized as xml PR #36919
- BreGoNunez: chore(docs): Add clarification for Pro Tip on Part 4 of tutorial PR #36918
- roryclaasen: chore(gatsby-link): Correct type export PR #36968