GatsbyJs v4 deferred static generation

Up until recently, the Gatsby framework has primarily been known as a feature-rich static site generator (SSG). This changed with the release of version 4, which includes more rendering options such as server side rendering (SSR) and deferred static generation (DSG), the latter of which will be the focus of this article.

TL;DR: Gatsby v4 DSG & Quick Links

What is Static Site Generation?

Before understating deferred static generation, we need a quick recap of how static site generation works. Each time a change is made to the SSG site, or data is changed or added, the site has to be “built.”

A build in Gatsby means that each React page component is converted into an actual HTML page, which is then served out to the client. This results in extremely fast page load, since the pages are “static” and ready to be served.

However, requiring a build after every change is a lot of overhead, and can quickly become infeasible for sites that require even a small amount of dynamic data. This is where deferred static generation comes in.

What is Deferred Static Generation?

DSG is an attempt by Gatsby to optimize the build process for SSG sites. Rather than requiring a full site build after each change, Gatsby only re-builds the necessary pages, and allows you to “defer” the build until the initial request to that specific page is made.

This new approach lowers overhead, and in-turn allows larger sites to consider SSG as a viable option.

Deferred Static Generation Workflow

Let’s take a look at the actual process of how DSG works, one step at a time.

  • Using the Gatsby createPage() method, pages are marked as deferred by setting an attribute to true, which we’ll show in an example.
  • The developer runs a build, or a build is triggered by using a build hook. The pages marked as deferred are skipped, but all other pages are built.
  • A user requests one of the pages that was marked as deferred. At this time, the page is generated and stored as a static asset to be served in the future.

Real-World Example of DSG Optimization

To illustrate the benefit of this rendering option, imagine a blog that has 20,000 articles. With a standard SSG implementation, this means at least 20,000 pages have to be rendered each time a build is required. That’s a lot of processing!

Imagine this same site with DSG configured to defer 19,000 of the articles, and only render 1,000 at build time. Perhaps the 19,000 articles are from the previous 3 years, and priority is given to the current year’s articles.

This configuration takes a lot of strain off the build process, without hurting page performance in any meaningful way. The first request made to a deferred static page will be slightly slower because the page is actually built at this time, but subsequent requests will act as a normal static page.

How to Use Deferred Static Generation with Gatsby v4

Gatsby makes implementing DSG a fairly simple process. Each Gatsby project includes a file called gatsby-node.js. Inside this file, Gatsby exports a method called createPages(), which allows work to be done during the build process of each individual page.

Within the createPage() method, we can now access an action the Gatsby provides by default, which also happens to be called createPage. This may sound a little confusing, but it’s quite simple in practice. Let’s take a look at the code:

exports.createPages = async ({ actions }) => {
            const { createPage } = actions;
                         path: "/using-dsg",
                         component: require.resolve("./src/templates/using-dsg.js"),
                         context: {},
                         defer: true,

As you can see, the createPage action takes an object as an argument, and in this object, we can pass a property called defer. Setting the defer property to true is all that is needed to utilize the DSG feature.

In this example, any page that utilizes the template called using-dsg.js will be included in the list of deferred pages. Simple right?

Gatsby DSG vs NextJs ISR

Incremental Static Generation (ISR) is another rendering option that was developed by the great people at NextJs. ISR is similar to DSG, but in this case the devil is in the details.

ISR isn’t a true SSG implementation. It’s actually just a fancy way to optimize SSR page performance by using an HTTP cache layer. So, when a NextJs page is requested utilizing ISR, the page will be built real-time as in any typical SSR setup, only the page will then be cached.

Due to the nature of caching data, ISR leads to the possibility of stale data, which is where DSG shines in this case. When a deferred page is built using Gatsby, the data always reflects the last build, which means data integrity will always be solid across all pages in the Gatsby site.

Gatsby DSG | Overview and Concluding Thoughts

Although DSG isn’t a silver bullet, it’s definitely a nice tool to have at the ready when developing SSG sites. As we’ve seen DSG allows us to minimize the build overhead by only building deferred pages when the initial HTTP request is made.

SSG sites tend to grow at unexpected rates sometimes. A site that was projected to grow at a fairly linear rate may begin to grow exponentially, leading to unforeseen stress on the hosting environment. 

DSG is a clever solution that preserves Gatsby’s excellent performance without much compromise. If your goal is to use Gatsby to achieve great SEO performance while adding a bit more scalability, deferred static generation just made that goal a reality.

Leave a Comment

oh my crawl logo
Digital Architecture
For Search Engines
Javascript Frameworks
Most Js Frameworks..
Brooklyn, NY 11219