Gatsby recently released incremental builds, an improvement that reduces the amount of work required to build a Gatsby site. In this post, we’ll learn how to enable Gatsby incremental builds on Netlify.

Step 1: Upgrade to Gatsby v2.20.4 or higher

Gatsby introduced incremental builds in version 2.20.4, so make sure to upgrade your Gatsby site to the latest version.

# this will upgrade to the latest version of Gatsby
npm install gatsby@latest

Step 2: Install cross-env

Most Windows command prompts will choke when you set environment variables as part of your build command. Cross-env will let us not worry about what environment we are using.

npm install cross-env

Step 3: Add the Gatsby Cache Netlify Build Plugin

Incremental builds rely on Gatsby’s cache, so we need to enable netlify-plugin-gatsby-cache, which will persist Gatsby’s public and .cache directories between builds.

You can use this one-click installation link for the Netlify UI, or you can read up on file-based Build Plugin installation in our docs.

Step 4: Add the flag to enable Gatsby incremental builds

Finally, update your build command in package.json (or wherever you’ve set your build command) to include the incremental builds flag:

    "scripts": {
      "develop": "gatsby develop",
-     "build": "gatsby build"
+     "build": "cross-env GATSBY_EXPERIMENTAL_PAGE_BUILD_ON_DATA_CHANGES=true gatsby build --log-pages"
    },

We’re adding the optional --log-pages flag here so we can see what Gatsby builds on each run — feel free to leave that out if you don’t want to see the extra logs.

Step 5: Make a change in your CMS and see the incremental builds!

Once we’ve made the above changes, our Gatsby site will run with incremental builds enabled! This means that changes from a supported CMS — Gatsby supports Contentful, Sanity, DatoCMS and CosmicJS at the time of writing with WordPress and Drupal support in alpha — Gatsby will only rebuild the parts of the site affected by the changed data.

If we look at our build logs, the first build will show a full build with all of our pages:

2:00:43 PM: info Done building in 41.429647017 sec
2:00:43 PM: info Built pages:
2:00:43 PM: Updated page: /design-research-program
2:00:43 PM: Updated page: /offline-plugin-app-shell-fallback/
2:00:43 PM: Updated page: /
2:00:43 PM: Updated page: /404/
2:00:43 PM: Updated page: /404.html

On repeat builds, we can see that the Gatsby build is much faster and only rebuilds the page that was changed:

2:03:56 PM: info Done building in 17.691847403 sec
2:03:56 PM: info Built pages:
2:03:56 PM: Updated page: /design-research-program

You can use Gatsby incremental builds today!

If you’ve got a Gatsby site, you can enable incremental builds today!

Give it a try, and enjoy builds that make your blazing fast Gatsby site even more blazinger! 🔥