The App Shell

When Cache Components is on, every route in your app is partially prerendered. At build time, Next.js renders each route's component tree and sorts the output into two piles:

• Content that can be known ahead of a request — static JSX, pure computation, and anything you cached with 'use cache' — is rendered now, into the route's static shell.
• Content that can't — uncached fetches, cookies(), headers(), dynamic params, searchParams — is left as a hole, and the <Suspense> fallback around it is rendered into the shell instead.

On a document request, the shell is served immediately — typically straight from a CDN, no origin server involved — and the holes are rendered at request time, streaming into their fallbacks as they resolve. The user sees a real page instantly, and the personalized or fresh parts pop in a beat later.

One sentence in that description deserves a second look: the shell is served on a document request. That's the contract. PPR's shell is an HTML artifact, addressed by URL, delivered when a browser asks for a page. Keep that in mind as we move to chapter 2, because it's exactly the assumption that's about to break.

After hydration, clicking a <Link> doesn't fetch a document. The router fetches an RSC payload — the serialized server-component tree for the destination — and grafts it into the running React app. Two consequences follow, and together they explain why PPR alone never made navigations instant.

Consequence 1: nobody serves you the HTML shell

The static shell you built in chapter 1 is sitting on a CDN, keyed by URL, waiting for a document request that isn't coming. A client navigation asks a different question — “give me the RSC data for /store/hats” — and in the old model, answering that question for a dynamic page meant rendering it on the server at click time. Until the response arrived, the router had nothing new to show. The old page just sat there.

Consequence 2: the transition re-renders less than a page load does

A client navigation keeps every layout that the current and destination routes share — that's the whole point of layouts. Only the tree below the shared layout re-renders. This sounds like a pure win, but it quietly disables a tool you've been relying on: a <Suspense> boundary in your root layout catches everything on a page load, but during a transition it sits above the re-render scope. It never fires. Whatever fallback story you wrote up there does not exist for navigations.

What the old router did about it

The pre-Cache-Components router wasn't naive — it prefetched. But its prefetching had a shape that stopped working the moment pages got dynamic:

And the fine print made it worse in practice:

• Route-level granularity. The cache was keyed per route, not per segment. Prefetches for /store/shoes and /store/hats couldn't share the store layout they had in common — each prefetch carried the whole thing.
• Coarse, short lifetimes. Client cache entries expired wholesale on a timer (staleTimes: five minutes for static content, and since v15, zero for dynamic — dynamic pages were effectively never reusable).
• The escape hatch was expensive. <Link prefetch={true}> forced a full prefetch — including the dynamic parts, cookies and all. One full server render per visible link, usually thrown away unclicked. Fine for one checkout button; ruinous for a feed of two hundred links.
• Miss the window, pay full price. A prefetch never blocks a navigation. If it hadn't landed (or had expired) by click time, the router went straight to a blocking server request.

So the old model gave you a hard choice for dynamic pages: navigate into a loading.js skeleton at best, block at worst, or pay for full prefetches per link. What it never gave you was the thing PPR gave document requests — a cheap, always-available, mostly-rendered starting point.

Remember the detail from chapter 1: the build-time prerender saves the shell in two forms. HTML, for document requests — and a serialized RSC payload, for exactly this moment. The shell was never only an HTML artifact. Cache Components puts the second form to work.

Here's the new model, end to end. While a page is idle, the router looks at the <Link>s in the viewport and quietly prefetches each destination's prerendered parts — the same green content from chapter 1, in RSC form, fetched per segment and stored in an in-memory cache. When the user clicks:

1. The router composes the next page synchronously from what's already in the cache. Shared layouts are kept in place; the new segments mount with their prefetched content. This is the paint at ~0 ms.
2. Any segment whose prefetched content was partial — it had holes — gets exactly one dynamic request, and the missing content streams into its <Suspense> fallbacks as it arrives. Fully prerendered segments don't contact the server at all.

The click stops being “ask the server, then render” and becomes “render, then let the server fill in the orange parts.” Which is precisely what PPR did for document requests — transplanted to the client.

Read that definition slowly, because each clause is load-bearing:

• “Per-route” — not per URL. There is one App Shell for /store/[slug], not one for every slug. Two hundred product links on a page share a single prefetched shell. Rendering a <Link> becomes effectively free, no matter how many point at the same route.
• “The parts that don't depend on URL-specific data” — the store nav, the page frame, and the fallbacks for anything slug-dependent. It's the destination's floor: what can be shown for any product before we know which product.
• “A session-personalized variant” — a shell isn't necessarily anonymous. If the route reads cookies() or headers(), the framework detects it and builds the shell for this user's session, cached per session in the browser rather than shared. Your logged-in nav can be part of the shell. (Chapter 6 covers how to make that actually work.)

So the full picture has two layers of “ready before the click.” The router prefetches the destination's prerender for the concrete URL when it can; the App Shell is the per-route floor that's always there — including when a link's specific prefetch hasn't landed yet, when there are too many links to prefetch individually, or when the URL was never prefetchable in the first place.

Theory over — let's build the store from the demo. The route is /store/[slug]: a product page showing details (name, price) that rarely change, and a live stock count that must be fresh on every request. The goal: clicking between products paints instantly.

Step 1 — Turn it on

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  cacheComponents: true,
}

export default nextConfig

One top-level flag. It enables the 'use cache' directive and its companions (cacheLife, cacheTag), turns on Partial Prerendering for every route, switches the router to per-segment prefetching, and — the part this guide cares about — generates App Shells. It also switches on validation, which you're about to meet.

Step 2 — Write the obvious thing, hit the guardrail

Here's the page the way you'd write it without thinking about shells at all:

import { db } from '@/lib/db'

export default async function ProductPage(props: PageProps<'/store/[slug]'>) {
  const { slug } = await props.params
  const product = await db.products.findBySlug(slug)
  const stock = await db.inventory.findBySlug(slug)

  return (
    <main>
      <h1>{product.name}</h1>
      <p>${product.price}</p>
      <p>{stock.count} in stock</p>
    </main>
  )
}

The dev overlay objects immediately:

This is the deal Cache Components strikes with you. Awaiting props.params at the top level makes the entire page depend on runtime data — nothing can be prerendered, there is no shell, and every navigation into this route would block on the server exactly like chapter 2. Rather than silently produce that experience, the framework makes you choose, per piece of data, one of three answers:

• Stream it — put it behind <Suspense>; the fallback joins the shell, the content arrives after the click.
• Cache it — give it a lifetime with 'use cache'; the real content joins the shell.
• Block on it — export const instant = false; an honest, explicit opt-out for routes where instant isn't worth the restructuring.

Validation runs in development on every page load and checks navigations too — including the “only re-renders below the shared layout” scenarios from chapter 2, which are nearly impossible to audit by hand across a growing app.

Step 3 — Carve the seams with Suspense

Answer one: push the awaits down, out of the page body and into children wrapped in <Suspense>. Pass params along as a promise — don't await it at the top — so the page component itself stays synchronous and prerenderable:

import { Suspense } from 'react'
import { db } from '@/lib/db'

type Params = PageProps<'/store/[slug]'>['params']

export default function ProductPage(props: PageProps<'/store/[slug]'>) {
  return (
    <main>
      <Suspense fallback={<ProductSkeleton />}>
        <ProductInfo params={props.params} />
      </Suspense>
      <Suspense fallback={<p>Checking stock…</p>}>
        <Stock params={props.params} />
      </Suspense>
    </main>
  )
}

async function ProductInfo({ params }: { params: Params }) {
  const { slug } = await params   // suspends here, inside the boundary
  const product = await db.products.findBySlug(slug)
  return (
    <>
      <h1>{product.name}</h1>
      <p>${product.price}</p>
    </>
  )
}

async function Stock({ params }: { params: Params }) {
  const { slug } = await params
  const item = await db.inventory.findBySlug(slug)
  return <p>{item.count} in stock</p>
}

Validation passes. The route now has a shell: the <main> frame, the store layout above it, and the two fallbacks. Navigations into this route paint instantly — but they paint skeletons. Structurally sound, visually disappointing: the App Shell for this route is all fallback, because everything interesting depends on the slug. Time to grow the green.

Step 4 — Grow the shell with 'use cache'

Product details rarely change — nobody renames a boot mid-session. The stock count is genuinely per-request. That asymmetry is the whole design input: cache the first, keep streaming the second.

async function ProductInfo({ params }: { params: Params }) {
  const { slug } = await params
  const product = await getProduct(slug)
  return (
    <>
      <h1>{product.name}</h1>
      <p>${product.price}</p>
    </>
  )
}

async function getProduct(slug: string) {
  'use cache'
  return db.products.findBySlug(slug)
}

Note what's cached: not the component, the data function. getProduct is keyed by its argument, so each slug gets its own entry with a real lifetime. That lifetime is the ticket into prerenders — when the router prefetches /store/hats, the server can include the cached product info in the prerendered payload it hands back. The stock count has no lifetime, so it stays orange: behind its fallback in every prerender, streamed only after a real navigation.

Run the demo's second mode again with this page in mind — it's exactly this code. Click a product: name and price paint at 0 ms (they came down with the prefetch), “Checking stock…” shows for the one thing that honestly needs a server, and streams in when it answers.

Step 5 — See it, then pin it down

Two tools close the loop. In dev, open the Next.js DevTools Navigation Inspector and toggle Pause on navigations: the next click freezes the page at its initial state, labeled Client nav, showing precisely what painted before any server response — your shell, with real cached content in it. (Pair it with the React DevTools Suspense panel to toggle individual boundaries.)

Then lock the behavior in CI with the instant() helper from @next/playwright, which scopes assertions to what's visible before dynamic content streams:

import { test, expect } from '@playwright/test'
import { instant } from '@next/playwright'

test('product info paints before the server answers', async ({ page }) => {
  await page.goto('/store/trail-boot')

  await instant(page, async () => {
    await page.click('a[href="/store/field-jacket"]')
    await expect(page.locator('h1')).toContainText('Field Jacket')
  })

  // after instant() exits, streamed content is allowed to land
  await expect(page.locator('text=in stock')).toBeVisible()
})

Chapter 4's story had one link and one destination. Real pages are feeds, tables, and sidebars — hundreds of <Link>s, many to the same route with different params. Prefetching each destination's full cached render, per URL, per visible link, adds up: it's chapter 2's “full prefetch per link” problem wearing a nicer outfit.

The App Shell's “per-route” property is the fix, and Partial Prefetching is the switch that makes it the default economics of <Link>:

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  cacheComponents: true,
  partialPrefetching: true,
}

export default nextConfig

With it on, a plain <Link> stops prefetching per-URL page content and loads just the destination's App Shell — one payload, shared by every link to that route, no matter how many are on screen. You then choose which links deserve more:

Notice what prefetch={true} means now. Before Cache Components it meant “prefetch everything, dynamic data and all” — a full server render per link that even pulled cookie-dependent content. Under Partial Prefetching it means “also ship the cached parts.” Uncached reads stay behind their fallbacks until a real navigation, always. The expensive, easy-to-misuse hammer became a scoped, predictable one.

It's worth pausing on how neatly the pieces now stack. Suspense seams and 'use cache' decide what's green (chapter 4). The App Shell packages the green that's URL-independent, per route. Partial Prefetching decides how much green ships before the click, per link. Three separate dials, each with a clear owner.

Everything green so far has been anonymous: the same product info for every user. But chapter 3's definition promised more — a session-personalized shell variant for routes that read cookies() or headers(). Your logged-in nav, the user's team, their currency. This chapter is about earning that.

One rule governs all of it, and it hasn't changed since chapter 4: a prerender only advances through content that has a cache lifetime. Prefetching happens before the click, so anything in a prefetched payload is by definition rendered ahead of time — and the framework will only render ahead of time what it's allowed to reuse. Uncached reads stay behind their fallbacks in every prerender, no matter which knobs you turn. What the knobs change is which request data is in scope when the prerender runs.

The obstacle, concretely

A dashboard layout with a personalized nav:

import { Suspense } from 'react'

export default function DashboardLayout({ children }: LayoutProps<'/dashboard'>) {
  return (
    <div>
      <Suspense fallback={<nav>…</nav>}>
        <UserNav />  // needs the session cookie
      </Suspense>
      <main>{children}</main>
    </div>
  )
}

The quiz at the end of chapter 4 told you why the naive fix fails: 'use cache' can't read cookies() — a shared cache entry can't contain one user's data. Two patterns resolve it, chosen by one question: is the result shared by many users, or tied to one?

Pattern 1 — Extract and pass (shared result)

import { cookies } from 'next/headers'

async function UserNav() {
  const team = (await cookies()).get('team')?.value  // read outside
  const topics = await getTopics(team)               // pass in
  return <nav>{topics.map(/* … */)}</nav>
}

async function getTopics(team: string | undefined) {
  'use cache'
  return db.topics.forTeam(team)
}

The cookie read stays outside the cached scope; only its value crosses in, as an argument. The cache entry is keyed by team, so everyone on the same team shares it — your database sees traffic proportional to the number of teams, not the number of users.

Pattern 2 — 'use cache: private' (per-user result)

async function getUser() {
  'use cache: private'
  const session = (await cookies()).get('session')?.value  // allowed here
  return db.users.findBySession(session)
}

The private variant may read request data directly, because its results are cached in the browser only — per user by construction, never on the server, and never part of the anonymous static shell. Reach for it when the value is inherently personal, or when the cookie read happens deep inside an auth helper you can't restructure around.

With either pattern in place, UserNav's content has a lifetime — so when the router builds this route's App Shell for this session, the personalized nav is in it. That's the “session-personalized variant” from the glossary definition, earned: the shell that prefetches for a logged-in user has their name already rendered, cached per session on the client rather than shared.

The last frontier: data that varies per link

One class of request data remains out of reach: values the App Shell can't know because they differ per destination URL — dynamic params not covered by generateStaticParams, and searchParams. A per-route shell can hold the session's nav, but it can't hold ?sort=price. For routes where that content is worth having before the click, opt in to runtime prefetching:

export const prefetch = 'allow-runtime'

export default function SearchPage(props: PageProps<'/search'>) { /* … */ }

Now a <Link prefetch={true}> pointing at this route triggers a runtime prerender: the server renders the route again at prefetch time, with the destination URL fully resolved — params, search params, cookies, headers all in scope. The same advancement rule applies: it renders through static and cached content (including 'use cache' keyed by runtime-derived arguments, and 'use cache: private'), and stops at uncached reads, which keep their fallbacks. More of the page is real before the click; only the honestly-fresh parts stream after it.

The cost model is the old full-prefetch one — a server invocation per visible link — which is why it's per-route opt-in and worth being deliberate about. Skip it when the App Shell already paints everything useful, when the URL-dependent content must be fresh anyway (the prerender would stop at the same fallback), or when the route is linked often but visited rarely. And note its role in the stack: runtime prefetching is a per-link upgrade, racing the user's click. The App Shell is the floor underneath it — if the click wins the race, the shell still paints. Runtime prefetching is currently experimental; expect its surface to move.

Every chapter so far has assumed the App Shell is what a <Link> prefetches. Turning that assumption on in an app you already have is its own small project — not because the switch is hard, but because it quietly changes what every link you've already written does.

The switch re-reads your links

Before Cache Components, a plain <Link> to a static page prefetched the whole page, and <Link prefetch={true}> went further still — it pulled dynamic, request-time data ahead of the click too. Partial Prefetching redraws both defaults:

• a plain <Link> now prefetches the App Shell, nothing URL-specific;
• prefetch={true} adds the route's cached content on top of the shell;
• prefetch={true} no longer pulls cookies, headers, or other request data ahead of time.

So flipping the flag doesn't only add a capability. It re-reads every <Link prefetch={true}> in your codebase — the ones you wrote for the old meaning still compile, but they mean something narrower now.

Don't flip the whole app at once

partialPrefetching: true in next.config.ts turns this on for every route in one commit. On a five-page site, do that and move on. On an app with hundreds of links and years of prefetch={true} habits, changing every link's behavior simultaneously is a lot to hold in your head — and a lot to review in one diff.

Adopt one route at a time

You don't have to. A single route can opt in ahead of the global flag:

export const prefetch = 'partial'

export default function Page() { /* … */ }

A <Link> pointing at a route with prefetch = 'partial' loads the App Shell only — the new behavior — while every other route keeps the old one. You convert the app route by route, each change small enough to reason about on its own.

Re-read every prefetch={true}

The flag is the easy part. The real work is the audit: each prefetch={true} you already wrote now means “ship the shell and the cached content,” not “ship everything.” Re-read each one with the intuition this guide has been building — ask what the destination actually is, in the two colors you already think in:

Once the flag is on and the audit is done, the whole system lines up with the model you've built: <Suspense> and 'use cache' decide what's in the shell, partialPrefetching makes the shell the default payload, prefetch={true} adds the cached content, and allow-runtime adds the per-link runtime prerender. There's nothing new to learn here — you're naming, in config, what you already understand.

Everything above works without knowing any of this. But if you open the network tab on a Cache Components app, here's how to read what you see.

1. PPR's static shell serves document requests; after hydration, every click is a client-side navigation, which the shell — as HTML — never serves.
2. Client navigations re-render only below the shared layout, so fallback plans that live above it (like a root-layout Suspense) don't exist during transitions.
3. Cache Components prefetches the destination's prerendered parts as RSC payloads, per segment, and composes them synchronously at click time — paint first, stream the rest.
4. The App Shell is the per-route floor of that system: everything URL-independent, shared by every link to the route, session-personalized when the route reads cookies or headers.
5. You shape what's in shells with two tools: <Suspense> decides where content yields to a fallback; 'use cache' (and : private) decides what has a lifetime and may therefore be rendered before the click.
6. Partial Prefetching makes the App Shell the default <Link> payload; prefetch={true} adds cached content; prefetch = 'allow-runtime' upgrades specific links with URL-resolved runtime prerenders.
7. Uncached reads join no prerender, ever — they stream after navigation, behind the fallback you chose for them. That invariant is what makes everything else safe.

Which tool, when

Further reading

In the Next.js docs, in roughly the order this guide followed: Caching (getting started — the full Cache Components mental model), Ensuring instant navigations (guides — validation and DevTools workflow), Adopting Partial Prefetching (guides — migration and the <Link> audit), Runtime prefetching (guides — experimental), and the Glossary entries for App Shell, Static Shell, and Partial Prefetching. The API references for 'use cache', 'use cache: private', cacheLife, and the prefetch route segment config cover the corners a tutorial shouldn't.