Migrate to Netlify Today

Netlify announces the next evolution of Gatsby Cloud. Learn more

ContactSign Up

The Gatsby Slice API: High Precision Incremental Builds

Josh Johnson
October 26th, 2022

Serving fully-rendered, static HTML files has made a few trips in and out of the web development sphere over the past few decades. As content-rich sites continue to get larger and larger, building out an HTML file for every single page can prove to be a difficult and time-consuming task. Since 2015, Gatsby has dedicated itself to solving this problem.

First, we made building HTML files fast, a key feature of Gatsby since its inception. With the launch of Gatsby 4, we made data handling fast with Parallel Query Running and made it possible to only build the files that matter with Incremental Builds. The success of Parallel Query Running and Incremental Builds continued on to the summer of 2022, when we made it possible to deploy only those files that changed with Incremental Deploys. Despite having all these incredibly speedy features, changing a marketing banner or navigation bar can still prove to be painful—every page needs to be rebuilt to pick up the changes.

Clearly, we’ve eliminated many, many causes of slower than expected builds. But, there’s still one type that we hear about from teams, and that’s the type of build that changes shared components re-used by all pages, like changing a navbar, footer, or other shared component.

Gatsby Slice API Header

Enter: The Gatsby Slice API

With the Gatsby Slice API in Gatsby 5, we not only have Incremental Builds, but High Precision Incremental Builds.

What does that mean? We’re glad you asked!

Picture this: you’re at a pizza party and everybody starts leaving. There’s a ton of pizza left because every pizza-party-thrower always orders too much. Nobody wants it to go to waste, right? It’s pizza! Here’s the thing… there’s a whole box of pepperoni pizza, but you really want one slice of supreme. You’re not going to take a whole box for the single slice, are you? You know you can only eat one pizza, so it would be inconsiderate to take both boxes! Naturally, you’d open the box, take out one slice of your pepperoni, and slide in one slice of supreme in its place. Now you still have a whole pizza, but with High Precision Incremental… pizza toppings.

Gatsby can build and ship individual pieces (or Slices) of your site and deploy only those that changed.

How does it work?

By calling the new createSlice action in your gatsby-node.js file, you can tell Gatsby to split that component out from the rest of the page. During the build process, Gatsby will remove that component from the full page HTML and later “stitch” the pieces together, kind of like sliding a piece of pizza into an empty spot of a pizza box. When Gatsby detects the underlying component has changed (with a little help from Incremental Builds), the HTML of that Slice will be updated and re-”stitched” into its place on the page.

Slices in Action

Code snippets are from the gatsby-starter-slices example

Let’s say we have a Layout component:

const Layout = ({ location, title, children }) => {
  const isRootPath = location.pathname === `/`

  return (
    <div className="global-wrapper”>
      <Header size={isRootPath ? 'large': 'medium'}>{title}</Header>
      <Footer />

This layout is used by every page on your 50,000 page site. Today, any time a change is made to the Header component, 50,000 pages need to be rebuilt.

Here’s a diagram of what a build process looks like without Slices:

A Gatsby build without Slices

Let’s convert the header to a Slice!

First, we have to call createSlice in our gatsby-node.js file:

exports.createPages = async ({ actions }) => {
    id: `header`,
    component: require.resolve(`./src/components/header.js`),

Then use the exported <code>Slice</code> component from <code>gatsby</code> in our Layout.

const Layout = ({ location, title, children }) => {
  const isRootPath = location.pathname === `/`

  return (
    <div className="global-wrapper">
      <Slice alias="header" size={isRootPath ? 'large': 'medium'}>{title}</Slice>
      <Footer />

That’s it! Now, any time the Header component changes, Gatsby only needs to build a single HTML file as opposed to 50,000.

Here’s a diagram of what a build process looks like with Slices:

A Gatsby build with Slices

Slices also supports running GraphQL queries, passing contexts, and swapping slices on a page-by-page basis using “aliases.” Check out our How-to documentation for more detailed examples or the Reference documentation for more technical information.

Want to watch a recorded demo? Check out our Gatsby 5 Alpha Showcase video!

Gatsby Cloud Optimizations

When using Slices in Gatsby Cloud, your site can make high precision incremental builds even faster. We already know Gatsby Cloud is the fastest way to deploy your Gatsby site (thanks Alex Barashkov!), so here we’re only running tests on Gatsby Cloud. 

We’ve set up some benchmarks to measure the impact Slices has on large, content-rich sites. In our test case, we set up a 10,000 page site sourcing from Contentful. With other cloud hosting providers, builds can take upwards of 20 minutes for this 10,000 page site. Gatsby Cloud is already 80% faster than that. By turning on a Slices Optimization toggle in the “Build features” of your site, updates for Slices can improve by another 80%, and in larger sites, even faster.

Here are the results:

Slices are 80% faster for code updates

As you can see, code updates to the Header component sped up by 78% by using Slices with Gatsby Cloud’s Slice Optimizations. Two minutes faster!

Slices are 50% faster for data updates

Likewise, we can see a 54% increase in build time for data updates to the Header component. By relentlessly pursuing making builds, of all kinds, fast we continue to enable teams to scale the composable web. 50% here, 70% there, 10x there, these wins add up!

Get Started with the Gatsby Slice API

The Gatsby Slice API is available to all in the Gatsby 5 Beta now and will reach General Availability in a few weeks. You can either try our gatsby-starter-slices sample starter or view our migration guide to upgrade your site to Gatsby 5. If you want to share your results or send the Gatsby team a pizza as a thank you (half kidding), feel free to hop in our GitHub Discussion or the #slices channel in Discord!

Share on TwitterShare on LinkedInShare on FacebookShare via Email

I like building things that make peoples' lives easier. I'm an Engineer turned Product Manager at Gatsby and a proud Yooper gone South.

Follow Josh Johnson on Twitter

Tagged with announcements, build-times, Gatsby 5, Gatsby Cloud, performance, Slice APIView all Tags

Talk to our team of Gatsby Experts to supercharge your website performance.

Contact Gatsby Now
© 2023 Gatsby, Inc.