Conditional Page Builds

One of the key differences between Gatsby v2 and Gatsby v3 is the new stability of conditional page builds, also known as incremental builds. In Gatsby v2, this experimental functionality was made available by enabling the GATSBY_EXPERIMENTAL_PAGE_BUILD_ON_DATA_CHANGES environment variable. The core capability of conditional page builds is the ability to regenerate only those static HTML files that need to be rerendered (thus requiring the .cache and public directories from the previous build to remain in place).

To accomplish this, Gatsby tracks certain inputs that influence the generation of HTML files, including the page template being utilized by the given page, the result of each page’s page query, the results of any static queries used by a page template, and any frontend source code (especially implementations of Gatsby’s Browser and SSR APIs). When these remain unchanged from the previous build based on the contents of the .cache and public directories, previous HTML files that were generated in prior builds can be reused untouched.

NOTE

For more information about how to use conditional page builds, and especially one key change that obligates developers to avoid direct filesystem calls in gatsby-ssr.js, consult the relevant sectionin the release notes for Gatsby 3.0 .