Skip to content

Next.js Cache Components and PPR: what the static shell contains

Next.js Partial Prerendering and SEO: what goes into the Cache Components static shell, what streams per request, and how to confirm your main content is in it.

By Crawlito · 9 min read

In short

  • With cacheComponents enabled, Next.js prerenders a static shell from static UI, use cache results and Suspense fallbacks, and streams anything that reads uncached data or a runtime API at request time.
  • Reading cookies(), headers(), searchParams or an unlisted params value removes that subtree from the shell, and only its nearest Suspense fallback is prerendered in its place.
  • A use cache scope joins the shell only if its lifetime is long enough: a revalidate of 0 or an expire under 5 minutes turns it into a dynamic hole, which rules out the built-in seconds profile.
  • In the next build route table, ○ means the whole page was prerendered, ◐ means a static shell plus streamed content, and ƒ means an empty prerender rendered on request.
  • HTML-limited bots such as Bingbot skip the prerendered shell and get a dynamic render, while crawlers outside that list, including GPTBot and ClaudeBot at the time of writing, get the shell with streamed parts appended.
On this page

With Cache Components, the static shell of a Next.js page is everything that can finish during the build: static markup, the output of use cache functions and components, and the fallback of every <Suspense> boundary that waits on uncached data or a runtime API. Anything inside those boundaries is rendered per request and streamed into the same response later. For AI search, the useful rule is short: if your main text is in the shell, it is in position in the HTML; if it sits behind a request-time boundary, the shell holds only a fallback.

This post covers how to tell which side of that line each part of a page is on, and how to move content into the shell. For the streaming format itself, the hidden div elements and why AI crawlers may handle them differently, see Next.js SEO for AI crawlers and SSR vs CSR for AI search.

How Partial Prerendering builds the shell

Cache Components is enabled with the top-level cacheComponents option, stable since Next.js 16.0.0. It replaces the old experimental.ppr, useCache and dynamicIO flags and makes Partial Prerendering (PPR) the default for App Router pages. At the time of writing, the docs also ask you to set partialPrefetching explicitly, because leaving it unset logs a warning:

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

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

export default nextConfig

Under this model, data fetching is dynamic by default. The Cache Components guide lists how the build treats each kind of work:

What the component doesWhere it ends up
Pure markup, module imports, fs.readFileSync, pure computationIn the static shell
Awaits data inside a use cache scope with a long enough lifetimeIn the static shell
Awaits uncached data (fetch, a database call) inside <Suspense>Fallback in the shell, content streamed per request
Reads cookies(), headers(), searchParams or an unknown params value inside <Suspense>Fallback in the shell, content streamed per request
Calls Math.random(), Date.now() or crypto.randomUUID()Must be cached, or deferred with connection() inside <Suspense>
Any of the request-time cases above with no <Suspense> boundaryBuild error

The shell is stored as HTML plus an RSC payload and, in the docs' words, can be served from a CDN without reaching your server. The streamed parts are appended to the same HTTP response once they resolve.

The last row of the table is the part that keeps pages honest. Next.js requires every page to produce a shell, so an uncached read outside any boundary fails the build with an error that starts like this:

Error: Route "/products/[id]": Next.js encountered uncached or runtime data during prerendering.

The building guide shows the three fixes it offers: stream it behind <Suspense>, cache it with use cache, or set export const instant = false to accept a blocking route. Each one puts your content in a different place, which is the decision that matters for crawlers.

How 'use cache' moves content into the shell

The use cache directive marks a function, component or whole file as cacheable. During the build, Next.js fills the cache entry and keeps rendering, so the result becomes part of the shell. A product description that would otherwise stream becomes plain HTML in place:

tsx
// app/products/[id]/page.tsx
// app/products/[id]/loading.tsx exists and is the fallback for unlisted IDs
import { cacheLife, cacheTag } from 'next/cache'

export async function generateStaticParams() {
  return (await getTopProducts()).map((p) => ({ id: p.id }))
}

async function getProduct(id: string) {
  'use cache'
  cacheLife('days')
  cacheTag(`product-${id}`)
  return db.products.find(id)
}

export default async function Page(props: PageProps<'/products/[id]'>) {
  const { id } = await props.params
  const product = await getProduct(id)
  return (
    <article>
      <h1>{product.name}</h1>
      <p>{product.description}</p>
    </article>
  )
}

For the IDs returned by generateStaticParams, the params are known and the data is cached, so the build prerenders each page in full. The docs' example, which keeps a loading.js file in the segment, shows these rows change from ◐ to ○ once the lookup is cached. Without that file or another <Suspense> boundary, the top-level await props.params blocks the fallback for unlisted IDs and the build fails.

Two rules decide whether a cached scope really lands in the shell.

The lifetime must be long enough. The cacheLife reference says a revalidate of 0 or an expire under 5 minutes excludes the result from prerenders, creating a "dynamic hole" resolved at request time. A stale under 30 seconds does the same, and a stale between 30 seconds and 5 minutes is prerendered but left out of the route's App Shell. Of the built-in profiles, only seconds falls under these thresholds, because its expire is 1 minute. If you omit cacheLife, the default profile applies: 5 minutes stale, 15 minutes revalidate, no time-based expiry.

Runtime APIs are not allowed inside. A cached function cannot call cookies(), headers() or read searchParams, and the restriction follows the call stack into any helper it calls. Read the value outside the cached scope and pass it in as an argument. That is fine for personalised widgets, but the result is then gated behind request data and is not part of the shell.

What pushes a subtree out of the shell

Request-time work only removes the subtree below the point where it is awaited. The problem is that it is easy to await it high up. The streaming guide puts it plainly: if you await params, searchParams, cookies(), headers() or a data fetch at the top of a layout or page, everything below that point becomes dynamic.

A common case is a layout that checks the session before rendering anything:

tsx
// Before: the whole layout and every page under it are out of the shell
export default async function Layout({ children }) {
  const session = (await cookies()).get('session')?.value
  return <Shell user={await getUser(session)}>{children}</Shell>
}

With loading.js above it, the build passes, but the shell for every page below is the loading skeleton. The article text, product details and headings all stream. Moving the read into a small component inside its own boundary keeps the rest in the shell:

tsx
// After: only the user menu streams
import { Suspense } from 'react'
import { cookies } from 'next/headers'

export default function Layout({ children }) {
  return (
    <Shell userMenu={<Suspense fallback={<MenuSkeleton />}><UserMenu /></Suspense>}>
      {children}
    </Shell>
  )
}

async function UserMenu() {
  const session = (await cookies()).get('session')?.value
  return <Menu user={await getUser(session)} />
}

params deserves its own note. For values returned by generateStaticParams, params is known during the build. For any other value it is runtime data. The ISR with Cache Components guide says that from Next.js 16.3 the first visit to an unlisted URL gets the generic App Shell with the URL-specific content streamed in, and Next.js then renders the page in the background so later visitors get the upgraded result from the cache. Earlier versions wait for a full server render instead. If the crawler is the first visitor to a long-tail URL, it gets the streamed version. List the URLs you care about in generateStaticParams. If the whole route can be static, ensureStatic = 'navigation' (added in 16.4.0) makes the first request wait for the complete static page, but it also fails the build on any uncached or runtime data, even inside <Suspense>.

searchParams is always request data on the server. If a filter or sort parameter is read at the page level, the listing streams for everyone. Read it in the component that needs it, inside its own boundary, as described in the useSearchParams CSR bailout guide.

How to read the next build route table

With Cache Components, the symbols in the route table describe how much HTML the build produced. From the building guide:

SymbolNameWhat it means for the page HTML
○StaticThe whole route was prerendered as HTML
◐Partial PrerenderA static shell was prerendered; the rest renders on demand and streams
ƒDynamicThe build accepted an empty prerender; the route renders on request

A product route with a few listed IDs and cached data looks like this:

Route (app)           Revalidate  Expire
┌ ○ /
├ ○ /_not-found
├ ○ /products                15m      1y
└   /products/[id]
  ├ ◐ /products/[id]
  ├ ○ /products/1            15m      1y
  ├ ○ /products/2            15m      1y
  └ ○ /products/3            15m      1y

The ◐ /products/[id] row is the fallback for IDs you did not list. The Revalidate and Expire columns show the shortest lifetimes of the caches a route contains: here the default profile's 15-minute revalidate and the default one-year expireTime.

◐ on its own does not tell you whether the main content is in the shell. A shell that contains only <p>Loading...</p> and a page where only the cart badge streams both print ◐. Use the symbol as a list of routes to inspect, then check the HTML. If a build fails and the stack trace only points at body and html, next build --debug-prerender gives readable stack traces; do not deploy that build.

How to check what is in the shell

The quickest test is to look at where your main text appears in the raw response. Text in the shell sits in its normal place in the markup. Streamed text arrives later, inside <div hidden id="S:0"> and similar elements, with a <template id="B:0"> placeholder where it belongs.

bash
URL='https://example.com/products/42'
UA='Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; GPTBot/1.4; +https://openai.com/gptbot'

curl -s -A "$UA" "$URL" > page.html

# 1. Is the main text in the response at all?
grep -c 'a sentence from the product description' page.html

# 2. How many streamed blocks does the response contain?
grep -o '<div hidden id="S:[0-9]*"' page.html | wc -l

# 3. Is the text in the shell? Keep only the HTML before the first
#    streamed block and drop inline scripts (the RSC payload), then search.
perl -0pe 's/<div hidden id="S:.*//s; s/<script\b.*?<\/script>//gs' page.html \
  | grep -c 'a sentence from the product description'

If step 3 finds the phrase, it is in the shell. If step 1 finds it but step 3 does not, it is streamed content or appears only inside a script payload. Dropping the scripts matters because the RSC payload can repeat page text in <script> tags, which can make streamed text look as if it arrived early. Repeat for a URL you did not list in generateStaticParams, twice, to see the first-visit and upgraded versions.

The user agent matters here. The streaming guide says HTML-limited bots skip the prerendered shell and are rendered dynamically, so that metadata can be placed in the <head>. At the time of writing, the default list in the Next.js source matches Bingbot, Applebot, DuckDuckBot, Google's special-purpose crawlers and many link preview bots, but not GPTBot, OAI-SearchBot, ClaudeBot or PerplexityBot. So the same URL can give a dynamic render with metadata in the <head> to Twitterbot/1.0 and the prerendered shell plus streamed blocks to GPTBot. In the streaming guide's own Twitterbot test the server sent one fully formed document, though the docs also say the rest of the page can still stream once metadata resolves. Test with the crawler you care about, not a browser. The curl guide has more variations, and raw vs rendered HTML explains why a browser's DevTools view is the wrong place to look.

That bot path has a failure mode of its own. The docs warn that if your shell depends on data that only exists during the build, an HTML-limited bot that re-renders the page can get an error, and the caching guide says these bots then receive a 500. Make sure every data source the shell uses is reachable at request time, then request the page as Bingbot to confirm.

A checklist for keeping main content in the shell

  1. Put the page's heading, body text, price and description in components that are static or cached, never behind a boundary that reads cookies, headers or search parameters.
  2. Give every use cache scope an explicit cacheLife longer than the thresholds above, and use cacheTag with on-demand revalidation for content that must update quickly.
  3. List the URLs that matter in generateStaticParams, and remember that it must return at least one param with Cache Components.
  4. Push runtime reads down into the smallest component that needs them, each in its own <Suspense>.
  5. Run next build, list the ◐ routes, and grep the raw HTML of one URL per route with an AI crawler's user agent.
  6. Request the same URL as Bingbot to confirm the dynamic bot render does not fail.

Frequently asked questions

Is Partial Prerendering bad for SEO?

Not by itself. Content in the static shell is in the HTML in its normal position. The risk is main content that streams per request, because it arrives later in the response inside a hidden element, and OpenAI, Anthropic and Perplexity do not document how their crawlers handle that.

Does every route need a static shell with Cache Components?

Yes, by default. The build fails if uncached or runtime data is read outside <Suspense>. You can opt a route out with export const instant = false, which allows a blocking route; if no shared layout provides a <Suspense> fallback, its prerender is empty and it shows as ƒ.

Does 'use cache' always put content in the shell?

No. It has to be reachable during the build, so it cannot sit below a runtime API read, and its lifetime must not be too short: a revalidate of 0, an expire under 5 minutes or a stale under 30 seconds make it a dynamic hole.

Do AI crawlers get the static shell or a full render?

It depends on the user agent. Bots in Next.js's htmlLimitedBots list skip the shell and get a dynamic render; at the time of writing GPTBot, ClaudeBot and PerplexityBot are not in the default list, so they get the shell with streamed parts appended. Setting htmlLimitedBots replaces the default list rather than extending it.

Check what crawlers receive

Once the build output looks right, confirm it on a live URL. The free check tests a single page with no account needed. For a whole Next.js site, an audit runs deterministic, rule-based checks on up to 500 pages, adds human review and delivers a PDF with evidence and prioritized fixes.

Filed under Rendering and content. Topics: nextjs, react, ssr, rendering, caching