If you build a large website with Gatsby or use Gatsby in combination with a CMS such as GraphCMS, the build can take a long time. For this reason Gatsby offers the option of an incremental build, see Conditional Page Builds. I hope this post helps you to reduce the build time.
TL;DR
- Use the environment variable
GATSBY_EXPERIMENTAL_PAGE_BUILD_ON_DATA_CHANGES
to enable conditional page builds. - Persist the
.cache
andpublic
directories between builds.
Behind the Scenes
In my example I used Gatsby in combination with GraphCMS and GitHub Actions. Whenever a change is made in the CMS, an Amazon Lambda function is triggered by a Webhook, which then triggers a build in GitHub Actions. If you want to learn more about it, check out the following blog post:
Static site builds with GitHub Actions and GraphCMS
Marco Streng ・ Aug 5 '20
How to use
Use the environment variable GATSBY_EXPERIMENTAL_PAGE_BUILD_ON_DATA_CHANGES=true
in your gatsby build
command to enable conditional page builds.
GATSBY_EXPERIMENTAL_PAGE_BUILD_ON_DATA_CHANGES=true gatsby build --log-pages
The --log-pages
parameter will output all the file paths that were updated or deleted at the end of the build stage.
You will need to persist the .cache
and public
directories between builds. This allows for comparisons and reuse of previously built files.
Github Actions
To persist the necessary directories I use GitHub cache action.
- name: Caching Gatsby
id: gatsby-cache-build
uses: actions/cache@v2
with:
path: |
public
.cache
key: ${{ runner.os }}-gatsby-build-${{ github.run_id }}
restore-keys: |
${{ runner.os }}-gatsby-build-
The key
is a unique cache identifier. This is important because you cannot currently update the cache manually after a build run. So after each build a new cache is created.
Caches that have not been accessed within the last week are cleared.
restore-keys
is a list of alternative keys that will be used to find the previous cache.
The complete GitHub Actions Workflow looks like this:
jobs:
build:
name: Build
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Use Node.js
uses: actions/setup-node@v1
with:
node-version: '12.x'
- name: Caching Gatsby
id: gatsby-cache-build
uses: actions/cache@v2
with:
path: |
public
.cache
key: ${{ runner.os }}-gatsby-build-${{ github.run_id }}
restore-keys: |
${{ runner.os }}-gatsby-build-
- name: Installing dependencies
run: yarn install
- name: Building Gatsby site
run: yarn build --log-pages
env:
GATSBY_EXPERIMENTAL_PAGE_BUILD_ON_DATA_CHANGES: true
CI: true
If you have any kind of feedback, suggestions or ideas - feel free to comment this post!
Top comments (1)
Thanks a lot. This was really useful!
FYI: This is not considered an incremental page build according to the Gatsby team: