How it works
The build stores three things per partial route: the shell HTML (ppr.html), its RSC segments for navigation, and a .meta file whose postponed field holds React's serialized resume state (replayNodes ending in "Suspense",1,[],0,["Suspense Fallback"…]). At request time, next start sends the shell bytes, then calls React's resume with that state and the live request. Only the postponed boundaries render; everything above them is not re-executed. The test API logged exactly two /prices calls across all runs: one from the build, one from a bot request (see Edge cases).
Reading the response chunk by chunk with fetch in Node 24 (cookie cart=abc):
55ms status 200
62ms +966B <main><h1>Store</h1><p>prices v<!-- -->7</p><!--$?--><template id="B:0"></template><p>Loading cart…</p><!--/$--></main>
82ms +4358B
85ms +4041B
2093ms +100B
2095ms +73B
2095ms +912B <div hidden id="S:0"><p>cart <!-- -->abc</p></div>
2096ms +14B
The headers were x-nextjs-prerender: 1, x-nextjs-postponed: 1 and Cache-Control: private, no-cache, no-store, max-age=0, must-revalidate, because the full response contains per-user content. The B:0 template marks the hole, S:0 carries its content, and the following $RC("B:0","S:0") call swaps them; that's React's streaming protocol, not something Next.js adds.
In headless Chrome 156 and Firefox 159, a MutationObserver saw Loading cart… at 27 ms and 16 ms, and cart empty at 2301 ms in both.
Edge cases
- Cache lifetime decides shell membership. The
cacheLife docs: revalidate: 0 or expire under 5 minutes is excluded from prerenders (a dynamic hole); stale under 30 seconds is too; stale between 30 seconds and 5 minutes is prerendered but left out of the App Shell used for prefetching. Of the presets, only seconds is affected. /short with cacheLife('seconds') inside <Suspense> built as ◐ with ticker loading in the shell.
- Unknown params get the App Shell. For a dynamic segment, Next.js also prerenders a URL-independent shell (
◐ /blog/[slug] in the route table) whose param-dependent parts are fallbacks. It's only useful if params is awaited inside <Suspense>, not at the top of the page.
- HTML-limited bots skip the shell. Next.js matches the user agent against a list (
Twitterbot, facebookexternalhit, Slackbot, Bingbot and others; not Googlebot, which got the shell). A Twitterbot request carried no x-nextjs-postponed header and showed prices v10: the cached component ran again at request time. The docs warn that data the shell needs at build time must also be reachable at request time, or the page fails only for crawlers.
- The shell's data is as old as the build until revalidated:
prices v7 stayed while the API's counter moved on.
Real-world scenario
A product page: name, images and description are use cache with cacheTag('product-123'); price and stock are short-lived; the cart badge and "recommended for you" read cookies. With PPR the browser paints everything but price, stock and the personalised parts from the shell, and fallbacks sized like the real content keep the swap from shifting layout. The same page without Cache Components is fully dynamic because of one cookie read.
Trade-offs
PPR gives nearly every route instant first bytes, but the shell is only as good as the tree's structure: an await high in a layout empties it, so the work is pushing request reads down into small boundaries. Fallbacks are visible UI and need design. Under next start the combined response is private, no-store, so a generic CDN in front cannot cache the shell; serving it from the edge relies on a platform that stores the shell and resumes the render separately. Streaming also needs every layer between server and browser to pass chunks through unbuffered.