Migrate to Netlify Today

Netlify announces the next evolution of Gatsby Cloud. Learn more

Deferred Static Generation API

Deferred Static Generation (DSG) allows you to defer non-critical page generation to the first user request, speeding up build times. Instead of generating every page up front, you can decide to generate certain pages at build time and others only when a user accesses the page for the first time. Subsequent page requests use the same HTML and JSON generated during the very first request to this page.

Note: This feature requires running NodeJS server. It is currently fully supported with gatsby serve and in Gatsby Cloud.

Creating deferred pages


Inside File System Route API templates you can export an async function called config that returns an object with the key defer:

Read the Deferred Static Generation guide to see a real-world example.


Creating deferred pages is almost identical to creating regular pages. The only difference is the new defer argument for createPage action. 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.

Working with deferred pages locally

Deferred static generation has no effect when using gatsby develop. You can work with pages locally as usual.

If you want to test deferred generation specifically, run gatsby build and gatsby serve from the command line. Deferred pages will be generated during the very first request to the page via gatsby serve.

Using in production

Deferred static generation requires a running NodeJS server. You can put NodeJS running gatsby serve behind a content delivery network (CDN) like Fastly, however that also requires additional infrastructure (like monitoring, logging, and crash-recovery).

Complete setup is available for you in Gatsby Cloud out-of-the-box.

How it works

The first request against a deferred page is a cache miss because the HTML/JSON wasn’t generated yet. On Gatsby Cloud the request is sent to a worker process that leverages an internal database to generate the data of the page. Once the page is generated it’ll be sent back to the user immediately. In the background, all generated artifacts are stored so that on a second request the cached response is directly served from the CDN. For that it bypasses the worker process completely.

When you directly visit a page you’ll get served the HTML. If you request a page on client-side navigation through Gatsby’s Link component the response will be JSON. Gatsby’s router uses this to render the page on the client. In the background, the JSON is stored and the HTML is generated so that on a second request of the page (including a direct visit) the page can be served from the CDN.

This all happens automatically and you only need to configure the defer key.

Current limitations

There are some limitations currently that you need to be aware of. We’ll do our best to mitigate them in our code, through contributions to upstream dependencies, and updates to our documentation.

Functions inside gatsby-config are not allowed

The gatsby-config file is bundled into the DSG engine and for this the file has to be serializable. Functions or callbacks can’t be used as they are not serializable.

DSG engine doesn’t support onCreateWebpackConfig

If you’re modifying Gatsby’s webpack configuration through onCreateWebpackConfig those changes won’t be applied to the DSG engine. The DSG engine is bundling everything it needs to run GraphQL queries, including your gatsby-node file with its createResolvers or createSchemaCustomization APIs. If you import/use files in those APIs that rely on your custom webpack changes (e.g. path aliases) it won’t work.

Additional Resources

Start building today on Netlify!
Edit this page on GitHub
© 2023 Gatsby, Inc.