What is Deferred Static Generation?
Deferred Static Generation (or DSG) — introduced in Gatsby 4 — is a rendering method that seeks to delay or defer the building of certain pages until run-time. These deferred pages are marked during build-time and then actually built during run-time.
Each of the deferred pages is only built a single time once deployed: only when that first user makes the request. When the request is made, the page is built on the fly, and content is rendered to the users. But after that first build, the page behaves exactly like any other static page.
So, what is actually happening with DSG?
When you mark a page as deferred in a Gatsby site, all of the necessary data is snapshotted at build time – meaning that the state of your site is atomic for both static and deferred pages. However, all deferred pages are omitted from static site generation at build time.
If you have 10,000 blog posts, for example, you could defer 9,000 of those pages so that they’re only generated when visitors request them. DSG uses data snapshotted at build time which means that the state of your site is atomic across pages both static and deferred pages.
A deferred page, upon 1st request ( seen below ), will result in a cache miss within Gatsby Hosting. Upon cache miss, Gatsby Hosting will then ask for that page to be generated by a Gatsby Cloud worker. Once that page is generated, it’s then cached at the CDN so that the subsequent requests ( e.g. 2nd Request, below ).
So, just remember that all you’re doing is marking a page to be deferred until the first visitor request. After that first visitor requests the deferred page, that page operates like any other Gatsby website page you’ve used in the past and has all the benefits of a static site.
How is DSG different then Incremental Static Regeneration (ISR)?
Incremental Static Regeneration (ISR) is a page rendering method developed by Next. With ISR, pages are also rendered in a hybrid manner, but changes are made across multiple builds, losing the benefits of atomic builds associated with the Jamstack. It is closer to Server-Side Rendering than DSG is since it “rehydrates” changes to the site at run-time.
A challenge with ISR is “updating on demand” and the lack of a true atomic build. Let’s look at a quick example. Let’s say you have a home page that is static and product pages that are using DSG or ISR. If the product information changes frequently, with ISR you could have a case where a product says available on the home page (static) but on clicking through says it’s unavailable or vice versa.
With DSG, the atomic build itself is snapshotted and used to supply the data for any deferred page until that built is updated. This means that if a build is deployed on Monday and a deferred page isn’t requested until Friday – it will build that page at run-time on Friday with the data from Monday’s deployment.
It also means that DSG is less brittle than ISR since it pulls data from our cached-at-build-time data layer – not a server-side API call.
How to use Deferred Static Generation?
Creating deferred pages is almost identical to creating regular pages. The only difference is the new defer argument for createPagesaction. When set to true, it tells Gatsby to exclude the page from the build step and instead generate it during the first HTTP request:
The defer argument is optional. If it’s excluded, the page will be generated at build time by default.
Choosing What To Defer
Choosing which pages to actually defer can be one of the more strategic choices you’ll make during build time. DSG is meant to be an arrow in your quiver so to speak and is not just a silver bullet. Its usage should be considered on a spectrum of trying to prioritize the developer experience vs the user experience of the site visitor. If you make a ton of updates and site performance across every single page is important to you – then you may way want to still statically generally all of your pages. But on the other hand, that performance hit is only to that first request, so the impact is minimal.
Let’s look at some good times to use DSG:
Deferring Older Blog Posts
Pass the published date of blogs into Gatsby node, then use it to pinpoint a range of blogs to defer. You could do something like “defer all blogs published more than 90 days old” or “defer all blogs not written in 2021”.
Deferring Less Popular SKUs
For eCommerce websites, DSG can be used to target categories or certain variants of products that may not be as popular as your best-selling items.
Deferring Past Versions Of Documentation
Documentation for past versions of software or hardware can take up thousands of pages but are necessary for customers. These pages can be deferred to render only when requested instead of taking up developer time during the initial build.