We’re taking a detour from ‘newer’ features to highlight some that are hugely impactful but often less understood. Deferred Static Generation (DSG) is one of the rendering methods released in Gatsby 4, and it’s a must-have feature for larger sites.
Let’s start by talking about what DSG is: a rendering mode for Gatsby that allows you to defer or delay building static pages until they are requested (run-time). You can tell Gatsby “don’t build this page until it needs to run,” and Gatsby will mark the page at build time but wait to build until you need the page. Keep in mind though that the pages in question still only build once– once DSG has built the page, the static content generated will be served from then on out.
So when would you use DSG? DSG is best for sites with a lot of pages because it cuts the time it takes to build these pages in bulk. . How? Well, DSG allows you to prioritize what pages you want to be the fastest by preventing builds on pages you specify, such as pages that are rarely visited. For example, a company’s blog may have older posts that are looked at a couple times a year – these types of posts could be marked with DSG so that they won’t be built until someone asks to read it. Another example is ecommerce sites, which typically have a wide variation in the popularity of product pages. Product pages for products that are less popular or less trafficked are a great use case for DSG, as DSG would build and serve these pages only on request – allowing the most visited pages to build at build time, and the rest build lightning-fast when requested.
Now, let’s talk about how you enable DSG in your Gatsby project.
Using DSG with Gatsby
You can follow along with the coding instructions below, or you can look at the finished code at this GitHub repo.
Setting up Development Environment
This tutorial assumes that you have Node.JS and npm installed, and for the Gatsby Cloud section, git installed and configured and a GitHub repository set up. First, we’ll clone a starter site that we’ll modify to use DSG. To begin, run the following in a directory that will contain the folder containing our project:
Now we can cd in and install the node modules we need with npm
Once the dependencies are installed, check in your `package.json` to make sure Gatsby is at at least version 4. Next we’ll take a look at the way we’ll add DSG into this site.
Adding DSG to our Site
We’re going to start by modifying the `gatsby-node.js` file. What we’re looking for is the `CreatePage` function. When we pass in pages we want to defer build on, we pass `defer: true`. Otherwise we pass `false`. For me, the code I needed to edit was at line 43:
This code sets `defer` to `true` when the page index is greater than zero. This will defer the earlier 2 of the 3 pages included in this starter.
That’s it! Passing `defer` into `createPage` set to `true` will enable DSG for your site.
You can also use the File System Route API to defer pages; you can learn more about that in the documentation.
Running DSG Locally
First, we’ll build locally:
This will build the first page, but defer the second and third to run-time build. You can see this in the output:
Now, to serve our local build, we run
It will give you a link to your site, and you can see the pages served when you click the links; and now those builds are deferred to run-time!
Next, we’ll take a look at deploying DSG on Gatsby Cloud
Using DSG on Gatsby Cloud
To start, take your new application and set up a git instance for it, then use git to push it to GitHub, GitLab, or BitBucket. This can be a public or private repository. Once it has been launched on GitHub head over to the Gatsby Cloud Dashboard and click the ‘Add Site’ button.
Select the provider you uploaded your code to, then the repository.
Click through the build options until you get to ‘Build Site’, then click it.
Your new site will start up a build right away. You’ll see your DSG pages under the ‘Raw Logs’ tab:
Go back to the project page and click the page URL to see your DSG site running in the cloud!
—
DSG gives you more flexibility in when and how your sites’ pages are built, and is very minimal to incorporate even into an existing Gatsby 4 site. It is instrumental for content-heavy sites that care both about user experience and build times. To learn more about DSG, check out the docs page on it and don’t forget to sign up for Gatsby Cloud if you’re not already.