# What is Deferred Static Generation (DSG) in Gatsby and When Should You Use It?

> Learn about Gatsby Deferred Static Generation DSG and how it speeds up build times for large websites by generating content on first user request. Optimize your Gatsby site today.

- Repository: [Gatsby/gatsby](https://github.com/gatsbyjs/gatsby)
- Tags: deep-dive
- Published: 2026-03-06

---

**Deferred Static Generation (DSG) is a Gatsby rendering mode that delays HTML/JSON generation until the first user request, reducing build times for large sites while serving cached static assets for subsequent visits.**

Gatsby supports three distinct rendering strategies: **Static Site Generation (SSG)**, **Server-Side Rendering (SSR)**, and **Deferred Static Generation (DSG)**. While SSG generates all pages at build time and SSR renders pages on every request, DSG offers a hybrid approach specifically designed to solve build-time scalability issues in the `gatsbyjs/gatsby` repository. This mode allows developers to ship sites with thousands of pages without waiting for every single page to build during continuous integration.

## How Deferred Static Generation Works Under the Hood

### The defer Flag in createPage

DSG is triggered by setting `defer: true` when creating pages programmatically. In [`packages/gatsby/src/redux/actions/public.js`](https://github.com/gatsbyjs/gatsby/blob/main/packages/gatsby/src/redux/actions/public.js), the `createPage` action accepts this flag and attaches it to the page object:

```js
// From public.js lines 172-174
{
  path: `/blog/${node.slug}/`,
  component: require.resolve(`./src/templates/blog-post.js`),
  context: { slug: node.slug },
  defer: true,  // Enables DSG for this page
}

```

### Mode Resolution Logic

During the build process, Gatsby determines each page's rendering mode through the resolver in [`packages/gatsby/src/utils/page-mode.ts`](https://github.com/gatsbyjs/gatsby/blob/main/packages/gatsby/src/utils/page-mode.ts) (lines 66-68). The system checks the explicit `defer` flag and, for File-System Route API pages, evaluates the exported `config` function to decide whether to treat the page as `SSG`, `SSR`, or `DSG`.

Pages that are forced to SSG include 404/500 error pages, as explicitly coded in [`page-mode.ts`](https://github.com/gatsbyjs/gatsby/blob/main/page-mode.ts) lines 70-77, ensuring critical error pages are always available immediately.

### First Request Materialization

Only pages whose mode is not `SSG` are written into the materialized page-mode store ([`page-mode.ts`](https://github.com/gatsbyjs/gatsby/blob/main/page-mode.ts) lines 99-107), allowing `gatsby serve` to identify which pages require lazy rendering.

When a request hits a DSG page:

1. The server executes the page's GraphQL queries
2. Renders the React component to HTML
3. Writes the resulting HTML/JSON to the build output
4. Returns the response immediately while caching the assets

Subsequent requests receive the cached static files directly, delivering identical performance to fully pre-generated pages.

## When to Use DSG for Large Gatsby Sites

DSG solves specific scalability challenges in large-scale Gatsby deployments. Consider implementing deferred generation in these scenarios:

| Situation | Why DSG Helps | Implementation |
|-----------|---------------|----------------|
| **Thousands of low-traffic pages** (old blog posts, archives, user-generated content) | Build time scales with page count. Deferring rarely visited pages can reduce build times by 30-70% according to v4.0 release notes. | Mark pages with `defer: true` via `createPage` or `config` export. |
| **Content changing infrequently but not needed at launch** | Ship quickly while supporting on-demand generation for omitted pages later. | Apply DSG to "future" content added after initial release. |
| **Sites with many locale-specific pages** (i18n with multiple language variants) | Generating every locale upfront multiplies build work. Deferring secondary locales reduces the build graph. | Use `defer: true` for non-primary locale pages. |
| **Pages with heavy GraphQL queries** | Query costs occur only on first request, not during every CI build. | Combine DSG with query caching on Gatsby Cloud for optimal performance. |

**Avoid DSG** for critical paths (homepage, checkout flows), 404/500 error pages (Gatsby forces SSG for these), or sites deployed to static-only hosts without Node.js server capabilities.

## Implementation Examples

### Using createPage with defer

Programmatically create deferred pages in [`gatsby-node.js`](https://github.com/gatsbyjs/gatsby/blob/main/gatsby-node.js):

```js
// gatsby-node.js
exports.createPages = async ({ actions, graphql }) => {
  const result = await graphql(`
    {
      allMdx(filter: { frontmatter: { draft: { ne: true } } }) {
        nodes {
          slug
        }
      }
    }
  `)

  result.data.allMdx.nodes.forEach(node => {
    actions.createPage({
      path: `/blog/${node.slug}/`,
      component: require.resolve(`./src/templates/blog-post.js`),
      context: { slug: node.slug },
      defer: true,               // ← DSG flag
    })
  })
}

```

The `defer` flag is defined in [`packages/gatsby/src/redux/actions/public.js`](https://github.com/gatsbyjs/gatsby/blob/main/packages/gatsby/src/redux/actions/public.js) lines 172-174.

### File System Route API Config Export

For pages created via the File System Route API, export a `config` function:

```js
// src/pages/blog/{Mdx.slug}.js
export async function config() {
  // Optional: Run GraphQL here to determine deferral logic
  return ({ params }) => ({
    defer: true,               // ← DSG enabled for this route
  })
}

```

This API is documented in [`docs/docs/reference/rendering-options/deferred-static-generation.md`](https://github.com/gatsbyjs/gatsby/blob/main/docs/docs/reference/rendering-options/deferred-static-generation.md) lines 14-27.

### DSG Page Component Structure

A minimal DSG page template looks identical to standard Gatsby pages:

```js
// src/templates/using-dsg.js
import * as React from "react"
import { Link } from "gatsby"
import Layout from "../components/layout"
import Seo from "../components/seo"

const UsingDSG = () => (
  <Layout>
    <h1>Hello from a <b>DSG Page</b></h1>
    <p>This page is not created until requested by a user.</p>
    <Link to="/">Go back to the homepage</Link>
  </Layout>
)

export const Head = () => <Seo title="Using DSG" />
export default UsingDSG

```

This example is available in the default starter at [`starters/default/src/templates/using-dsg.js`](https://github.com/gatsbyjs/gatsby/blob/main/starters/default/src/templates/using-dsg.js).

## Key Source Files and Architecture

Understanding the internal implementation helps debug DSG behavior in production:

| File | Purpose |
|------|---------|
| [`packages/gatsby/src/redux/actions/public.js`](https://github.com/gatsbyjs/gatsby/blob/main/packages/gatsby/src/redux/actions/public.js) | Defines the `createPage` action including the `defer` parameter (lines 172-174). |
| [`packages/gatsby/src/utils/page-mode.ts`](https://github.com/gatsbyjs/gatsby/blob/main/packages/gatsby/src/utils/page-mode.ts) | Resolves page modes (`SSG`, `SSR`, `DSG`) and forces SSG for error pages (lines 66-68, 70-77, 99-107). |
| [`docs/docs/reference/rendering-options/deferred-static-generation.md`](https://github.com/gatsbyjs/gatsby/blob/main/docs/docs/reference/rendering-options/deferred-static-generation.md) | Official DSG documentation covering API usage and limitations (lines 14-27, 66-73). |
| [`starters/default/src/templates/using-dsg.js`](https://github.com/gatsbyjs/gatsby/blob/main/starters/default/src/templates/using-dsg.js) | Minimal runnable DSG page example in the default starter template. |
| [`docs/docs/how-to/rendering-options/using-deferred-static-generation.md`](https://github.com/gatsbyjs/gatsby/blob/main/docs/docs/how-to/rendering-options/using-deferred-static-generation.md) | Step-by-step implementation guide for real-world DSG scenarios. |

These files illustrate how DSG is expressed in the API, how Gatsby decides to treat a page as deferred, and how developers can enable it in their projects.

## Summary

- **Deferred Static Generation (DSG)** delays HTML/JSON creation until the first user request, caching results for subsequent static serving.
- Enable DSG by setting `defer: true` in `createPage` (defined in [`packages/gatsby/src/redux/actions/public.js`](https://github.com/gatsbyjs/gatsby/blob/main/packages/gatsby/src/redux/actions/public.js)) or returning `defer: true` from a File System Route `config` export.
- Gatsby determines page modes in [`packages/gatsby/src/utils/page-mode.ts`](https://github.com/gatsbyjs/gatsby/blob/main/packages/gatsby/src/utils/page-mode.ts), forcing SSG for error pages regardless of defer settings.
- DSG requires a running Node.js server (`gatsby serve` or Gatsby Cloud) and cannot deploy to pure static hosts.
- Ideal for large sites with thousands of low-traffic pages, heavy GraphQL queries, or multi-locale content that would otherwise inflate build times.

## Frequently Asked Questions

### What is the difference between DSG and SSR in Gatsby?

**Server-Side Rendering (SSR)** generates HTML on every single request, making it suitable for personalized or highly dynamic content. **Deferred Static Generation (DSG)** generates HTML only on the *first* request, then caches and serves the result statically for all subsequent visitors. According to the Gatsby source code in [`packages/gatsby/src/utils/page-mode.ts`](https://github.com/gatsbyjs/gatsby/blob/main/packages/gatsby/src/utils/page-mode.ts), both modes bypass the build-time SSG pipeline, but DSG persists the output to disk while SSR does not.

### Can I use DSG with static hosting platforms like Netlify or Vercel?

**No.** DSG requires a running Node.js server to handle the initial request generation and subsequent caching. Static hosting platforms that only serve pre-built files from a CDN cannot execute the on-the-fly rendering logic implemented in `gatsby serve`. To use DSG, you must deploy to Gatsby Cloud, a Node.js server environment, or any hosting solution that supports server-side execution.

### How does DSG affect SEO and page performance?

**SEO impact is minimal** if you configure your hosting correctly. While the first request incurs a slight delay (cold start) as Gatsby generates the HTML, subsequent requests receive cached static files with identical performance characteristics to SSG pages. Search engine crawlers typically receive the cached version after the first visit. However, critical landing pages should remain SSG to guarantee instant availability for all visitors, as recommended in the DSG documentation.

### Which pages should not use Deferred Static Generation?

**Avoid DSG** for high-traffic entry points (homepage, product pages, checkout flows), 404/500 error pages, and any content required for immediate site functionality. The Gatsby source code in [`packages/gatsby/src/utils/page-mode.ts`](https://github.com/gatsbyjs/gatsby/blob/main/packages/gatsby/src/utils/page-mode.ts) (lines 70-77) explicitly forces SSG mode for error pages regardless of developer configuration. Additionally, pages that must be available offline or served from pure static CDNs cannot use DSG due to its server-side rendering requirement.