Skip to content

SPA, SSR and hydration

Partial prerendering in Next.js 16: what the static shell holds

Read a Next.js 16 page built with Cache Components: what lands in the prerendered shell, what streams later in the same response, and how to measure the split.

By Cerys Eaton, SiteRender team · Published

This article was drafted with AI assistance from the sources listed below and edited and published by the SiteRender team.

Reading a partially prerendered page
  1. 1Read to the endThe shell arrives first; Suspense content arrives later in the same response.
  2. 2Measure the splitCompare text before the first hidden S: fragment with text in the whole response.
  3. 3Check the fallbacksCount template B: placeholders; each one is a section that was not in the shell.
  4. 4Fetch twiceAn unlisted URL can get the App Shell first and an upgraded page on the next visit.
  5. 5Ignore the 200The shell starts a 200 response before the request-time content is known.

You fetch a page built with Next.js 16. The first bytes arrive at once and hold the header, the navigation and a few "Loading..." lines. The response stays open, and more HTML follows. That is partial prerendering. Whether your reader gets the text depends on what was in the first part, and on whether it waits for the rest.

What partial prerendering is, from the reading side

Cache Components shipped in Next.js 16.0.0 and is switched on with cacheComponents: true in next.config. New App Router apps created with the recommended create-next-app defaults already have it enabled, together with Partial Prefetching. With Cache Components, Partial Prerendering (PPR) is the default rendering behavior.

At build time, Next.js renders each route and produces a static shell: HTML for direct page loads plus a serialized RSC payload for client navigation. The shell can be served straight from a CDN. Whatever could not finish at build time renders on request and streams into the same response.

For a reader, that splits every page into two parts: what was knowable at build time for every visitor, and what was not.

What goes into the shell

The Next.js caching docs list what ends up in the shell:

  • Predictable work: module imports, synchronous reads such as fs.readFileSync, and pure computations complete during the prerender.
  • Cached results: the output of a use cache function or component, as long as its lifetime is not too short.
  • Fallbacks: for each <Suspense> boundary, the fallback UI, not the content behind it.

What stays out: components that read cookies(), headers(), searchParams, dynamic params that were not prerendered, and uncached fetches. They render at request time behind their fallback.

"Too short" has documented thresholds. A cache with a revalidate of 0, or an expire under 5 minutes, is excluded from prerenders and becomes a "dynamic hole" resolved at request time. A stale under 30 seconds also keeps it out of prerenders, and a stale of at least 30 seconds but under 5 minutes keeps it out of the route's App Shell. Of the preset cacheLife profiles, only seconds crosses that line, through its expire of 1 minute. So a widget cached with cacheLife('seconds') is never in the shell, even though it is cached.

One change from the older model matters when you compare old and new captures: reading cookies() no longer makes the whole route dynamic. The static and cached parts still ship in the initial HTML, and only the boundary around that read waits.

What streams later, and where it lands

The Next.js streaming guide shows the order of chunks for a page with two Suspense boundaries:

  1. The shell: <head>, CSS, navigation, fallback skeletons, one <template id="B:0"> placeholder per boundary, and bootstrap scripts.
  2. Component payload chunks, as self.__next_f.push calls.
  3. Each resolved boundary, as a <div hidden id="S:0"> with the finished HTML and a script that swaps it into the B:0 spot.

All of it is one HTTP response. A static fetch that reads to the end of the body has the text. A fetcher that stops at the first chunk, or gives up on a short read timeout, keeps the shell and its "Loading..." lines. How the hidden fragments look in a grep is covered in where the SSR grep misleads.

Do not read the status code as a signal either. With Cache Components, Next.js sends the prerendered shell while the request-time check runs, which starts a 200 response even when the shell has no visible UI.

Measure the split

curl buffers its output by default, and the streaming guide notes that a script that reads the body as a stream is more reliable than curl for observing timed chunks. This one also measures how much text sits before the first streamed fragment:

// shell-split.mjs: node shell-split.mjs https://example.com/
const url = process.argv[2] ?? "https://example.com/";
const start = Date.now();
const res = await fetch(url, { headers: { "Accept-Encoding": "identity" } });
const decoder = new TextDecoder();
let html = "";
for await (const chunk of res.body) {
  html += decoder.decode(chunk, { stream: true });
  console.log(`+${Date.now() - start}ms  ${html.length} chars so far`);
}

const text = (s) =>
  s.replace(/<(script|style)[\s\S]*?<\/\1>/gi, " ")
   .replace(/<[^>]+>/g, " ")
   .replace(/\s+/g, " ")
   .trim();
const cut = html.search(/<div hidden id="S:\d+"/);
const shell = cut === -1 ? html : html.slice(0, cut);

console.log("status", res.status);
console.log("fallback placeholders", (html.match(/<template id="B:\d+"/g) ?? []).length);
console.log("streamed fragments", (html.match(/<div hidden id="S:\d+"/g) ?? []).length);
console.log("text before first fragment", text(shell).length, "chars");
console.log("text in whole response", text(html).length, "chars");

The Accept-Encoding: identity header turns off compression, so a compression layer does not hold chunks back.

Read the last two lines together. Close numbers: the main text is in the shell, and any fetcher reads it. A large gap with several fragments: the main text streams, so read to the end of the response and check what your extractor keeps. Zero fragments and little text: the content is not in this response at all, and the rendering-mode classifier is the next step.

Same URL, two different first responses

Dynamic routes add a twist. For a URL whose params were listed in generateStaticParams, Next.js serves the fully prerendered page. For a URL whose params were not, and with Partial Prefetching on, it serves the App Shell at once, the generic part of the page that does not depend on the URL, and streams the param-specific parts in. Then it renders that URL in the background with the now-known params, and later visitors get the upgraded result. If every data access in it is cached, the upgrade is a fully static page.

The docs date this: the App Shell for unlisted params is served from Next.js 16.3, while earlier versions wait for a full server render before sending the response. The docs also say these caches are scoped to a single deployment, and a new deploy starts fresh.

So a first fetch of a rarely visited product URL can show more fragments than the second. Run the script twice before you decide what the page sends, and never store a fallback line as the page's content.

Test it yourself

Pick one page on a Next.js 16 site you run, and one dynamic URL on it that nobody has visited since the last deploy. Run shell-split.mjs on each, twice. Note the gap between shell text and full text, and whether the fragment count drops on the second run. A small gap means a static fetch with any timeout reads the page. A large gap means the reader has to wait for the end of the response, and the extraction step has to handle hidden fragments.

Frequently asked questions

What is in the static shell of a Next.js partially prerendered page?

Everything Next.js could render at build time: static markup, module imports and other predictable values, results of use cache functions with a long enough lifetime, and the fallback UI of every Suspense boundary. Components that read cookies, headers, search params or uncached data are not in the shell; only their fallback is.

Does a static fetch get the streamed parts of a partially prerendered page?

Yes, if it reads the response to the end. The streamed sections arrive later in the same HTTP response, as hidden div fragments with a script that swaps them into place. A fetcher that stops after the first chunk or on a short read timeout keeps only the shell and its loading fallbacks.

Why does the same Next.js URL return different HTML on the second request?

With Cache Components and Partial Prefetching, from Next.js 16.3 a URL whose params were not prerendered gets the generic App Shell on its first visit, with the param-specific parts streamed in. Next.js then renders the page in the background and the next visitor gets the upgraded result.

Is partial prerendering on by default in Next.js 16?

Partial prerendering is the default behavior once Cache Components is enabled with cacheComponents: true. New App Router apps created with the recommended create-next-app defaults already have Cache Components and Partial Prefetching enabled.

Sources

  1. Caching (Next.js docs) (Documentation)
  2. ISR with Cache Components (Next.js docs) (Documentation)
  3. cacheLife (Next.js docs) (Documentation)
  4. Streaming (Next.js docs) (Documentation)
  • · SPA, SSR and hydration

    Reading Next.js hydration data without a browser

    Next.js pages often ship their content as JSON in the first response. Where to find __NEXT_DATA__ and the App Router payload, and how to parse them safely.