Rendering Strategies - A Decision Map

Two worlds, one framework

Everything in the Patterns track depends on one line in next.config.ts. Read this section first. The rest of the notes keep saying "with Cache Components" and "legacy".

// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  cacheComponents: true, // the Next 16 model: PPR, 'use cache', cacheLife
  partialPrefetching: true, // set it explicitly; leaving it unset logs a warning
}

export default nextConfig

The two config sets do not mix. With Cache Components on, the SWC transform rejects dynamicParams, dynamic, fetchCache, revalidate and experimental_ppr exports with "Route segment config "…" is not compatible with nextConfig.cacheComponents. Please remove it."¹ Going the other way, instant, prefetch and ensureStatic fail the build without cacheComponents.² For what partialPrefetching changes on the client, see How much a link prefetches.

The six strategies at a glance

Two more patterns sit across these: server-prefetched client caches (26) and the two auth styles (27, 28). Auth is a rendering decision too. Reading a session cookie on the server makes that subtree request-time.

The decision flowchart

Start from the content, not from the acronym. The questions are about who the content is for and when it changes.

flowchart TD
  A[New page] --> B{Needs a Node server<br/>at runtime?}
  B -- "No: static host only" --> SPA["SPA / static export<br/>(25)"]
  B -- Yes --> C{Same output<br/>for every visitor?}
  C -- Yes --> D{Changes after<br/>deploy?}
  D -- No --> SSG["SSG<br/>(21)"]
  D -- "Yes: on a schedule<br/>or on publish" --> ISR["ISR<br/>(21)"]
  C -- "No: parts depend on<br/>cookies, headers, query" --> E{Is there a useful<br/>shared shell?}
  E -- Yes --> PPR["PPR: shell + Suspense holes<br/>(23)"]
  E -- "No: whole page<br/>is per request" --> SSR["SSR<br/>(22)"]
  PPR --> F{Part only makes sense<br/>in the browser?}
  SSR --> F
  F -- Yes --> CSR["CSR island<br/>(24)"]

Three questions settle almost every case:

1. Same for everyone? If yes, the page is static, and the only question left is how often it changes (SSG vs ISR).
2. Is there a shell? Most "dynamic" pages have a header, navigation, product details or an article body that is the same for everyone. With Cache Components that part is prerendered and only the personal bits stream. Pure SSR is right only when nothing useful can be shown before the request data is known.
3. Does it need the browser? Geolocation, localStorage, a WebSocket, a token that only the browser holds. That part is CSR whatever you chose for the rest.

How Next decides: the prerender is the test

There is no static analysis that marks a page "dynamic". At build time Next runs your components in a prerender and records what happens. The mechanism is two AsyncLocalStorage stores that every request API reads.

workStore and workUnitStore

• The WorkStore describes the route being rendered. It has the route name, the incremental cache, and the legacy switches forceDynamic, forceStatic and dynamicShouldError. It also has dynamicUsageDescription and dynamicUsageStack, which become the "why is this route dynamic" message.⁵
• The WorkUnitStore describes what kind of render is running right now. It is a tagged union: request, the cache stores ('use cache', unstable_cache), the prerender stores, and build-time-generator (used while generateStaticParams runs).⁶

The prerender stores are the important ones here:

The modern server store also carries the renderSignal and the abort controller. Its comment calls the controller "the boundary between Prerender and dynamic", and says it is aborted "after one task, or when you call a sync API which requires the prerender to end immediately".⁷

One API, five behaviours: cookies()

cookies() is the clearest example. It reads both stores and switches on the work unit type:⁸

// packages/next/src/server/request/cookies.ts (simplified)
export function cookies(): Promise<ReadonlyRequestCookies> {
  const workStore = workAsyncStorage.getStore()
  const workUnitStore = workUnitAsyncStorage.getStore()

  if (workStore.forceStatic) return makeUntrackedCookies(createEmptyCookies()) // dynamic = 'force-static'
  if (workStore.dynamicShouldError) throw new StaticGenBailoutError(/* dynamic = "error" */)

  switch (workUnitStore.type) {
    case 'cache':                 throw createCookiesInUseCacheError(route)   // not allowed in 'use cache'
    case 'build-time-generator':  throw new Error(/* not inside generateStaticParams */)
    case 'prerender':             return makeHangingCookies(workStore, workUnitStore)  // Cache Components
    case 'prerender-legacy':      return throwToInterruptStaticGeneration('cookies', workStore, workUnitStore)
    case 'prerender-runtime':     return stagedRendering.delayUntilStage(/* sessionData */)
    case 'request':               return /* the real cookies */
  }
}

The two prerender branches are the two worlds:

• Legacy: throwToInterruptStaticGeneration builds a DynamicServerError, sets prerenderStore.revalidate = 0, records the expression on the work store, and throws.⁹ The build's export step catches dynamic-usage errors and records the route with cacheControl: { revalidate: 0 }. That is how a route becomes ƒ.¹⁰
• Cache Components: makeHangingCookies returns makeSessionDataHangingPromise(...). That is a promise that never resolves. It rejects only when the render signal aborts, and it records that session data was read.¹¹¹² Nothing throws. The component simply never finishes during the prerender.

searchParams, headers(), connection() and a fetch with cache: 'no-store' follow the same pattern. Each one is a hanging promise in 'prerender' and an interrupt in 'prerender-legacy'.¹³¹⁴¹⁵

Static vs partial vs dynamic in the build output

After the prerender, the build prints one symbol per route. The function that chooses it is short and worth reading:¹⁶

// packages/next/src/build/utils.ts (simplified)
if (pageInfo.isRoutePPREnabled) {               // Cache Components
  if (pageInfo.hasEmptyStaticShell ||
      (pageInfo.isDynamicAppRoute && !pageInfo.hasPostponed)) return 'ƒ'
  if (!pageInfo.hasPostponed) return '○'         // fully static
  return '◐'                                     // static shell + holes
}
if (pageInfo.isStatic) return '○'
if (pageInfo.isSSG) return '●'                   // generateStaticParams paths
return 'ƒ'

The legend reads ○ (Static), ● (SSG), ◐ (Partial Prerender) prerendered as static HTML with dynamic server-streamed content and ƒ (Dynamic) server-rendered on demand.¹⁷ With Cache Components you will mostly see ○ and ◐. A ƒ there means the prerender produced an empty shell, which is the SSR case in part 22.

The Cache Components prerender in one picture

With Cache Components the prerender runs twice. That is what makes "abort after one task" safe for code that uses caches.

sequenceDiagram
  participant B as next build
  participant R as Prospective render
  participant C as Caches ('use cache')
  participant F as Final render
  B->>R: render with store type 'prerender'
  R->>C: fill every reachable cache
  C-->>R: cacheSignal.cacheReady()
  R-->>B: discard output
  B->>F: render again, caches are warm
  F->>F: advance stages in sequential tasks
  F-->>B: abort, pending Suspense = holes
  B->>B: prelude HTML + postponed state

1. Prospective render. React's prerender runs until every cache read has settled. Next waits on cacheSignal.cacheReady() before it aborts this pass.¹⁸ The code comment explains why: "we can't synchronously abort the render when a dynamic API is used during the initial render because we need to ensure all caches can be filled".¹⁹
2. Final render. Now every 'use cache' result is in memory and resolves at once. Next renders again inside runInSequentialTasks, moves through the render stages one task at a time, and then aborts the React controller.²⁰²¹ If the stream is still pending at that point, the result is marked partial: "we have blocked for longer than a Task and we assume there is something unfinished".²²

That timing rule is how a plain database call becomes dynamic even though Next never patched your ORM. Uncached I/O cannot finish inside a few synchronous tasks. Cached reads can. Anything still waiting is a hole. Part 23 follows the holes into the postponed state and the resume.

Every route must produce a shell

The Cache Components model adds a rule the legacy one never had. A pending hole must sit inside a <Suspense> boundary. During validation each hole is matched against its component stack. A hole under a Suspense boundary counts as allowed dynamic. A hole with no boundary above it becomes an error ("blocking route" in the dev overlay).²³ After the render, throwIfDisallowedDynamic fails the build if the prelude is not complete and errors were collected. The two opt-outs are checked first: allowEmptyStaticShell and a Suspense boundary above <body>.²⁴ allowEmptyStaticShell is set when a segment exports instant = false.²⁵²⁶

So with Cache Components every uncached or request-time access needs one of three fixes:

What counts as dynamic

The legacy row for plain fetch comes from the previous-model docs: a fetch without a cache option "is fetched once during next build if it is reachable before any Request-time APIs".³⁰ The Date.now() row is one of the biggest behaviour changes. In legacy mode a timestamp silently froze into the HTML. With Cache Components the dev overlay flags it and asks you to choose (part 05).

The same page in both worlds

A product page: shared details, a personalised "in your cart" badge.

// app/products/[slug]/page.tsx (Cache Components)
import { Suspense } from 'react'
import { cookies } from 'next/headers'
import { cacheLife, cacheTag } from 'next/cache'

export async function generateStaticParams() {
  return [{ slug: 'coffee-grinder' }] // at least one, or the build fails
}

export default function Page({ params }: PageProps<'/products/[slug]'>) {
  return (
    <>
      <Suspense fallback={<h1>Loading…</h1>}>
        <Details params={params} />
      </Suspense>
      <Suspense fallback={<span>Cart</span>}>
        <CartBadge params={params} />
      </Suspense>
    </>
  )
}

async function Details({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params
  const product = await getProduct(slug)
  return <h1>{product.name}</h1>
}

async function getProduct(slug: string) {
  'use cache'
  cacheLife('hours')
  cacheTag(`product:${slug}`)
  return db.product.findUniqueOrThrow({ where: { slug } })
}

async function CartBadge({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params
  const cart = (await cookies()).get('cart')?.value?.split(',') ?? []
  return <span>{cart.includes(slug) ? 'In your cart' : 'Cart'}</span>
}

Build result: ◐. The details are in the shell, the badge streams.

// app/products/[slug]/page.tsx (legacy, no cacheComponents)
import { cookies } from 'next/headers'

export const revalidate = 3600

export default async function Page({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params
  const product = await fetch(`https://api.example.com/products/${slug}`, {
    next: { tags: [`product:${slug}`] },
  }).then((r) => r.json())
  const cart = (await cookies()).get('cart')?.value // makes the WHOLE route dynamic
  return <h1>{product.name} {cart?.includes(slug) && '(in cart)'}</h1>
}

Build result: ƒ. One cookie read turned the route into SSR, and revalidate = 3600 now only governs the fetch cache. To keep the page static in legacy mode you would move the badge into a Client Component that reads the cart through an API: CSR (part 24).

Common misconceptions

Summary

Next.js decides static vs dynamic by running your code in a prerender and listening to the request APIs. Each API reads the workUnitStore. In the legacy model a dynamic access throws DynamicServerError and the route becomes ƒ. With Cache Components the API returns a hanging promise. The final prerender is aborted after a few tasks, and every pending Suspense boundary becomes a hole in a static shell. That is why PPR is the default there, and why a route must always produce a shell unless it opts out with instant = false. Choose a strategy per region of the page: same for everyone means SSG or ISR, per request with a useful shell means PPR, no shell means SSR, browser-only means CSR, and no server at all means a static export. The next parts walk through each one, starting with SSG and ISR.

Key takeaways

• Two worlds: cacheComponents: true brings component-level PPR, 'use cache' and instant/ensureStatic. The legacy dynamic/revalidate/fetchCache/dynamicParams exports are a compile error there.
• PPR is not a flag any more: with Cache Components every App Router page is PPR-enabled, and experimental.ppr throws.
• workUnitStore.type: every request API switches on it. 'prerender' gives a hanging promise, 'prerender-legacy' throws, 'request' gives real data.
• Legacy detection: throwToInterruptStaticGeneration sets revalidate = 0 and the export step records the route as dynamic.
• Cache Components detection: a prospective render fills caches, then a final render is aborted after sequential tasks. Anything still pending is a hole.
• Shell rule: holes must be inside <Suspense>. The opt-outs are instant = false or Suspense above <body>.
• Short caches are holes: 'use cache' with revalidate: 0 or expire under 5 minutes is not prerendered.
• Build symbols: ○ static, ● SSG (legacy), ◐ partial prerender, ƒ dynamic or empty shell.
• Decide per region: same for everyone (SSG/ISR), useful shell (PPR), no shell (SSR), browser-only (CSR), no server (SPA).

← Configuration · Index · SSG & ISR →