Rendering Options in Gatsby: How to Choose Between SSG, DSG, and SSR

Gatsby supports three per-page rendering strategies—Static Site Generation (SSG) for build-time static HTML, Deferred Static Generation (DSG) for on-demand first-request generation, and Server-Side Rendering (SSR) for dynamic per-request rendering—that you can mix within the same site to optimize performance and freshness.

The gatsbyjs/gatsby repository provides flexible rendering options that let you apply different strategies to individual pages based on their specific data and traffic requirements. Unlike monolithic architectures, Gatsby allows you to keep most pages as static HTML while deferring or server-rendering only those that need dynamic content, significantly improving build times and runtime performance according to the source code in docs/docs/conceptual/rendering-options.md.

Overview of Gatsby Rendering Modes

Gatsby’s three rendering modes are implemented per page, meaning you can configure one route as SSG and another as SSR within the same application.

Static Site Generation (SSG)

SSG is the default rendering option that runs at build time when you execute gatsby build. It produces fully-rendered HTML and JSON assets that are cached forever on your CDN. Because the content never changes after deployment without a rebuild, this mode is ideal for blog posts, marketing pages, and documentation that remains static.

No additional configuration is required to use SSG. Any page component exported from src/pages or created via actions.createPage without special flags automatically uses this mode.

Deferred Static Generation (DSG)

DSG skips rendering during the initial build and instead generates the page on the first request. After the first visitor triggers the generation, the resulting static assets are cached on the CDN and served to subsequent visitors exactly like SSG pages. This approach is documented in docs/docs/reference/rendering-options/deferred-static-generation.md.

Use DSG for low-traffic or rarely updated pages—such as archive posts, old documentation, or large paginated lists—where you want to reduce initial build times without sacrificing the performance benefits of static delivery.

Server-Side Rendering (SSR)

SSR renders HTML on every request using a Node.js server. By exporting an async getServerData function from your page component, you can fetch fresh data, access request headers, set custom status codes, and deliver personalized content for each visitor. As implemented in docs/docs/reference/rendering-options/server-side-rendering.md, this mode is essential for authentication-protected pages, A/B testing, e-commerce checkout flows, and content that changes by the minute.

Because a server process runs for each request, SSR is slower than SSG and DSG, but it provides the most dynamic experience possible in Gatsby.

How to Choose the Right Rendering Option for Each Page

Follow this decision framework when architecting your pages:

1. Can the page be generated once and remain valid indefinitely?
   Use SSG. This is the default behavior and requires no extra configuration.

2. Is the content static but rarely accessed, making build time a concern?
   Use DSG. Mark the page with defer: true to generate it only when first requested, reducing your total build duration.

3. Does the page require up-to-date data, user authentication, or request-specific personalization?
   Use SSR. Export getServerData to handle dynamic logic on every request.

You can mix these modes freely across your site. The Gatsby CLI outputs a build summary indicating how many pages fall into each category, helping you verify your configuration.

Implementation Examples

SSG: The Default Behavior

Create a standard page component without special exports to use Static Site Generation:

// src/pages/about.js
import * as React from "react"

export default function About() {
  return <h1>About us – static page</h1>
}

No additional code is required; Gatsby pre-renders this HTML at build time.

DSG: Deferring Page Generation

You can enable DSG using either the createPage action in gatsby-node.js or the File-System Route API config function.

Using createPage in gatsby-node.js:

The underlying implementation in packages/gatsby/src/redux/actions/public.js respects the defer flag when creating pages programmatically:

// gatsby-node.js
exports.createPages = async ({ actions, graphql }) => {
  actions.createPage({
    path: "/old-archive/2020/",
    component: require.resolve("./src/templates/archive.js"),
    context: { year: 2020 },
    defer: true,               // ← mark as DSG
  })
}

Using the File-System Route API config function:

// src/pages/archive/{year}.js
export async function config({ params }) {
  // Defer all archive pages older than 2022
  const defer = Number(params.year) < 2022
  return { defer }
}

Both methods tell Gatsby to skip rendering these pages at build time and instead generate them on the first request.

SSR: Fetching Fresh Data on Every Request

Export getServerData to switch a page to Server-Side Rendering. For a real-world reference, see starters/default/src/pages/using-ssr.js:

// src/pages/random-dog.js
import * as React from "react"

export default function RandomDog({ serverData }) {
  return (
    <>
      <h1>Random Dog</h1>
      <img src={serverData.message} alt="A random dog" />
    </>
  )
}

// The SSR entry point
export async function getServerData() {
  const res = await fetch("https://dog.ceo/api/breeds/image/random")
  const data = await res.json()
  return { props: data }
}

When Gatsby detects the getServerData export, it routes requests for this page through the Node.js server instead of serving static files.

Summary

• SSG generates HTML at build time for content that never changes, requiring no extra configuration and delivering the fastest response times via CDN caching.
• DSG defers generation until the first request, reducing build times for low-traffic pages while still serving static assets to subsequent visitors.
• SSR processes every request through a Node.js server, enabling real-time data fetching and personalization at the cost of higher latency.

Frequently Asked Questions

Can I mix SSG, DSG, and SSR in the same Gatsby site?

Yes. Gatsby’s architecture allows you to assign different rendering options to individual pages within the same application. You can maintain the majority of your site as SSG while selectively applying DSG to archive content and SSR to authenticated dashboard pages.

How do I enable DSG for specific pages only?

You enable DSG by setting defer: true either in the createPage action inside gatsby-node.js or by exporting a config function from a File-System Route API template. Gatsby will skip these pages during the build and generate them on-demand when first requested.

What are the performance implications of using SSR?

SSR requires a Node.js server to run getServerData and render React on every request, making it significantly slower than SSG or DSG which serve pre-built files from a CDN. Reserve SSR for pages that absolutely require real-time data or user-specific content that cannot be statically generated.

When should I choose DSG over SSG?

Choose DSG when you have thousands of old blog posts, documentation pages, or pagination routes that receive minimal traffic but would unnecessarily extend your build time if generated at build time. DSG keeps your builds fast while still delivering static HTML after the first visitor loads the page.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}