Using Deferred Static Generation (DSG)
Introduction
Deferred Static Generation (DSG) is one of Gatsby’s rendering options and allows you to defer non-critical page generation to user request, speeding up build times. Instead of generating every page at build time, you can decide to build certain pages up front and others only when a user accesses the page at run time. For large sites, with content that is infrequently visited (e.g. old blog posts or certain content types), this can dramatically reduce build times.
In this guide, you’ll learn how to modify your createPage calls to only build your preferred pages up-front and leave the rest deferred to the first user request. You’ll also learn how to use DSG with File System Route API.
For full documentation on all options, see the Reference Guide on Deferred Static Generation.
Prerequisites
Before you begin, you should already have:
- An existing Gatsby site. (Need help creating one? Follow the Quick Start.)
- Either a
gatsby-node.jsfile where you’re creating pages with thecreatePagesAPI or a page template that uses the File System Route API
Directions
File System Route API
The general process for using DSG looks like this:
Exporting an async function called
configthat returns an object with the keydefer
For the purpose of this guide, let’s assume you have a blog powered by markdown (using gatsby-transformer-remark) and have a date & slug key inside the frontmatter of each file. You want to defer all posts that are older than 2021-10-31.
A markdown file could look something like this:
Your page component would look something like this:
You’re creating paths like /my-first-post as the frontmatter__slug is used. Then the component displays the result of the page query.
Now you need to add the async config function:
Inside the graphql call (which you can only use in the outer function) you can query any data you like. In this instance all posts older than 2021-10-31 are queried with their slug. The inner function has access to params that get passed through with File System Route API.
So at the end you compare the current slug (params.frontmatter__slug) with the set of all posts that are older than 2021-10-31. If the current slug (and thus the current post) is inside this set, the page is marked as deferred.
gatsby-node.js
The general process for using DSG looks like this:
Adding
defer: trueto yourcreatePagecall.
For the purpose of this guide, let’s assume you have a blog powered by MDX and have blog posts dating back years (with 1000 blog posts in total). Via your analytics tracking, you’re seeing that only the latest 100 posts are regularly visited. The rest gets occasional or no visits at all.
The gatsby-node.js file:
For this example, it’s important that inside the gatsby-node.js the result is sorted by date and in an descending order. Depending on your use case you might need to adjust the query to sort differently or query additional information (e.g. a “category” field from the frontmatter) besides the slug.
This way you can use the index in the forEach to apply defer to all but the latest 100 posts:
The first 100 pages will receive defer: false, the other 900 pages receive defer: true.