Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 72 ยท Rendering Strategies

Partial Prerendering

Learn Partial Prerendering in Next.js 16: a static shell served instantly with dynamic parts streamed in, how Cache Components enable it, and its tradeoffs.

Until now we treated each route as either static or dynamic. That is a crude choice for real pages. A shop's home page is 95% the same for everyone: the logo, the navigation, the featured products. The one personal bit is a small "Welcome back, Ana" greeting and a cart count. Because of that tiny part, a classic dynamic page makes every visitor wait for a full server render of everything.

Partial Prerendering (PPR) removes that trade-off. The route is split in two: a static shell, prerendered at build time and served instantly, and dynamic holes, which are rendered per request and streamed into the same response. You get the first-byte speed of a static page and the personalization of a dynamic one. This lesson explains the model, how to write it with Cache Components, and what it costs. It combines ideas from Static vs Dynamic Rendering and Streaming with Suspense.

One route, two kinds of content

Static shell plus dynamic holes

Shell Prerendered once, served instantly.
Holes Rendered per request, streamed in.

Both arrive in the same response.

1 / 3

PPR is not a separate renderer you switch on page by page. It is what happens when a page contains both prerenderable content and Suspense boundaries around the parts that cannot be prerendered.

Turning it on: Cache Components

In Next.js 15, PPR was an experimental flag (experimental.ppr) with a per-route export. In Next.js 16 it became part of Cache Components, one setting in your configuration:

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

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

export default nextConfig;

With this on, the model flips compared with older versions. Instead of "static unless you use a request-time API", the rule is "dynamic unless you cache it or Next.js can prove it is static". Everything that can finish at build time (plain markup, components marked with 'use cache') lands in the shell. Anything that needs the request or fresh data must sit inside a Suspense boundary, and it becomes a hole. The 'use cache' directive itself, with cacheLife and cacheTag, is the subject of The use cache Directive and Cache Components.

A page written for PPR

TSX
// app/page.tsx
import { Suspense } from 'react';
import { cookies } from 'next/headers';
import { cacheLife } from 'next/cache';
import { getFeaturedProducts } from '@/lib/data/products';

export default function Home() {
  return (
    <main>
      <h1>Lamp Shop</h1>
      <FeaturedProducts />
      <Suspense fallback={<p>Loading your greeting...</p>}>
        <Greeting />
      </Suspense>
    </main>
  );
}

async function FeaturedProducts() {
  'use cache';
  cacheLife('hours');
  const products = await getFeaturedProducts();
  return (
    <ul>
      {products.map((product) => (
        <li key={product.id}>{product.name}</li>
      ))}
    </ul>
  );
}

async function Greeting() {
  const cookieStore = await cookies(); // needs a request: this is a hole
  const name = cookieStore.get('name')?.value ?? 'guest';
  return <p>Welcome back, {name}</p>;
}

Walk through what Next.js does with it:

  1. The h1 is plain markup, so it belongs to the shell.
  2. FeaturedProducts reads data but is cached for hours, so its output is also baked into the shell (and refreshed in the background according to cacheLife).
  3. Greeting reads cookies. It cannot run at build time, so the shell contains the fallback from its Suspense boundary instead.

At build time Next.js stores the shell along with a note of where the holes are. At request time it sends the shell immediately, renders only the holes, and streams their HTML into the places the fallbacks occupy.

sequenceDiagram
  participant B as Browser
  participant C as Shell cache
  participant S as Server
  B->>C: GET /
  C-->>B: Static shell, fast
  C->>S: Render the dynamic holes
  S-->>B: Stream the greeting HTML
  Note over B: Fallback replaced by content

The browser gets useful HTML right away; the personal parts follow in the same response.

What the "shell cache" is depends on where you host: a CDN or edge location on a platform that supports it, or the server's own stored output when you self-host. Either way, the shell is not recomputed for each visitor.

The rule Next.js enforces

If a component reads request data or does uncached work outside a Suspense boundary, Next.js cannot decide what belongs in the shell, and next build stops with an error that tells you to add a boundary or cache the data. That is a feature: it forces every dynamic part of a page to be an explicit, visible hole instead of silently making the whole route dynamic. Values that change on every call, such as the current time or random numbers, are treated the same way, so use them inside a boundary, or call await connection() first to say "this part is request time".

Real or stand-in? The next.config.ts flag, 'use cache', cacheLife, cookies and Suspense code above is real Next.js 16, shown read-only because it needs a Node.js server and a build step. The two live examples below are React stand-ins: they re-create the timeline and the shell/hole decision with ordinary components and timers.

Seeing the timeline

The first stand-in compares two versions of the same page side by side. Time is virtual: the clock jumps in 50 ms steps. In the fully dynamic version, nothing can be sent until the personal greeting is ready at 600 ms. In the PPR version, the shell is ready after 50 ms and the greeting fills in later. Press Replay to watch again.

Dynamic page versus PPR

The finished pages are identical. The difference is the experience between 50 and 600 ms: the dynamic version shows nothing, while the PPR version already shows the logo and the product list.

Deciding what is shell and what is a hole

The second stand-in lets you play compiler. Each component has a kind (plain markup, cached data, request data, or uncached data) and a flag saying whether it is wrapped in Suspense. Click the buttons to change them, and the page tells you where each component lands, or whether the build would fail.

Shell, hole or build error?

At first the build fails, because StockLevel does uncached work outside a boundary. Click its Suspense button to put it inside one, and the build passes with two holes. Or click its kind until it says 'use cache' data, and it moves into the shell. Those are exactly the two fixes in real Next.js: wrap it, or cache it.

Tradeoffs

PPR is powerful, but it is not free.

Benefit Cost
Instant first byte from a prebuilt shell Every dynamic part needs a thoughtful fallback
Personalization without a fully dynamic page The shell cannot contain personal data, so personal parts always appear after a skeleton
Slow data no longer delays the page Content can shift when holes fill in, so skeletons should match the final size
Uses ordinary React and Suspense You must audit every async access: cache it or wrap it
One response for static and dynamic parts Hosting must support streaming responses end to end; some proxies buffer them

A good rule is to make the big, stable parts of the page cached or static, and keep the holes small and meaningful: a greeting, a cart count, a stock badge. If most of a page is a hole, you are paying for the complexity without getting the benefit, and a plain dynamic page or a client-side widget may be simpler.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does Partial Prerendering produce for a route?

    PPR splits one route into a prerendered shell and dynamic holes that arrive in the same response.
  2. 2. In Next.js 16, which setting turns on the PPR model?

    PPR became part of Cache Components in Next.js 16. The older experimental.ppr flag belonged to Next.js 15.
  3. 3. A component reads cookies() and is NOT inside a Suspense boundary, with Cache Components on. What happens?

    Next.js needs every dynamic part to be an explicit hole, so it refuses to guess and stops the build.
  4. 4. Which part of a page belongs in the static shell?

    Plain markup and cached components can finish at build time, so they go in the shell. Request data and uncached work become holes.

Summary

  • Partial Prerendering serves a prerendered static shell instantly and streams dynamic holes into the same response.
  • In Next.js 16 it comes from cacheComponents: true; the rule becomes "dynamic unless cached or provably static".
  • Plain markup and 'use cache' components go in the shell; cookies(), headers(), searchParams and uncached work must sit in Suspense boundaries and become holes.
  • Missing boundaries are a build error, which keeps every dynamic part explicit.
  • Keep holes small, give fallbacks the right size, and make sure your hosting streams responses without buffering.

Next: Node.js and Edge Runtimes