How do you enable Partial Prerendering in a Next.js 15+ application?

First, enable the experimental flag in next.config.ts: experimental: { ppr: 'incremental' }. Then, export export const experimental_ppr = true within specific page.tsx or layout.tsx route segments.

What is Partial Prerendering (PPR), and what fundamental web challenge does it solve?

PPR resolves the tradeoff between static speed (SSG) and dynamic personalization (SSR). Within a single route, it compiles an immutable Static Shell during build time for instant Edge CDN delivery (sub-30ms TTFB), while dynamically rendering personalized data on the server during request time and streaming it into the open HTTP connection.

What role do React Suspense boundaries play in PPR architecture?

Suspense boundaries act as the architectural boundary between static and dynamic code. Everything outside Suspense is compiled into the build-time Static Shell. Components inside Suspense that access dynamic APIs (cookies, headers, searchParams) become dynamic holes represented by fallback skeletons at build time.

What happens if a route with experimental_ppr = true accesses await cookies() outside a Suspense boundary?

Next.js halts the build with a fatal Prerender Error, stating that dynamic data was accessed without a Suspense boundary. This prevents developers from accidentally turning an entire static page shell into a dynamic SSR route.

How does the low-level React.postpone() mechanism work in PPR?

During build-time prerendering, calling dynamic APIs causes React to throw a signal via React.postpone(). The compiler freezes the branch, embeds the fallback skeleton into the static artifact, and allows runtime servers to resume execution strictly from that freeze point without re-evaluating static parent components.

How does Partial Prerendering differ from standard Streaming SSR?

Standard Streaming SSR starts only when an incoming request hits the server: the server dynamically renders layouts and shells before streaming. PPR pre-compiles and caches the shell at build time, so TTFB is delivered instantly (< 30 ms) from Edge CDN caches like a static asset.

Why cannot searchParams be read inside layout.tsx when using PPR?

Layouts in the App Router are persistent and do not re-render across subpage navigation, which allows them to be permanently cached in the Static Shell. Reading searchParams inside layouts would invalidate shell caching, so Next.js restricts searchParams to page.tsx.

How is the connection() function from next/server used in PPR?

await connection() signals to the Next.js compiler that component execution must be deferred until client connection time (triggering React.postpone()), ensuring a heavy component streams dynamically even if it does not explicitly access cookies() or headers().

Partial Prerendering (PPR) in Next.js: Hybrid Static and Dynamic Streaming — Next.js 16 App Router

Q: Why cannot searchParams be read inside layout.tsx when using PPR?

Layouts in the App Router are persistent and do not re-render across subpage navigation, which allows them to be permanently cached in the Static Shell. Reading searchParams inside layouts would invalidate shell caching, so Next.js restricts searchParams to page.tsx.

Q: How is the connection() function from next/server used in PPR?

await connection() signals to the Next.js compiler that component execution must be deferred until client connection time (triggering React.postpone()), ensuring a heavy component streams dynamically even if it does not explicitly access cookies() or headers().

Why This Matters#

Throughout the history of web development, engineers had to make an architectural compromise between Static Site Generation (SSG) and dynamic server-side rendering (SSR):

Static Site Generation (SSG): Delivers near-zero response times (TTFB under 30 ms) by distributing pre-built HTML files from global Edge CDN networks, but cannot render personalized user content without client-side delays.
Dynamic Rendering (SSR): Generates unique data for every incoming user request (shopping cart, authentication status, localized preferences), but requires cold starts on compute functions and blocking database queries, delaying the first byte of response (TTFB 200–800 ms).

Attempting to resolve this dilemma on the client side (shipping a static loading skeleton followed by a client-side fetch in useEffect) severely harms Core Web Vitals: layout shifts (CLS), interaction delays (INP), and client-side network waterfalls.

Partial Prerendering (PPR) eliminates this compromise at the architecture level. PPR compiles the static shell of the page (Layouts, navigation, footers, fallback skeletons) at build time, while dynamically rendering personalized interface zones on the server upon incoming request and streaming them into the very same continuous HTTP connection.

Mental Model#

Partial Prerendering bifurcates the page lifecycle into two distinct execution phases:

Build-time Prerender Pass: The Next.js compiler traverses the component tree during next build. Static sections of the route are pre-rendered into an immutable Static Shell. When the compiler encounters a <Suspense> boundary containing calls to dynamic runtime APIs (await cookies(), await headers(), dynamic searchParams), the runtime triggers the React Postpone API. Execution of that dynamic subtree is suspended, the fallback skeleton is embedded into the Static Shell, and a Dynamic Hole marker is generated. The finalized Static Shell is uploaded to Edge CDN caches.
Request-time Resume Pass: When a user requests the URL:
- The Edge CDN initiates an Edge Premature Flush, returning the Static Shell instantly. The browser paints the visual page layout and skeletons in milliseconds.
- The origin application server (Node.js/Edge runtime) simultaneously resumes rendering strictly from the postponed boundaries (Resuming), without re-evaluating static ancestor components.
- As dynamic queries resolve, the server flushes the HTML and RSC chunks into the open HTTP stream, and the browser seamlessly replaces the skeletons with live, interactive content.

Two-Phase Architecture of Partial Prerendering#

text

PHASE 1: PROJECT COMPILATION (next build / Build-time Prerender Pass)
─────────────────────────────────────────────────────────────────────────────
Compiler traverses route component tree:
[Root Layout] ──► [Navigation] ──► [Static Products] ──► [<Suspense>]
                                                             │
                                                    cookies() encountered!
                                                             │
                                                  React.postpone() ──┐
                                                                     ▼
[Persist to Static Shell (HTML + RSC)] ◄── [Embed CartSkeleton fallback]
          │
          ▼
   Deploy to Edge CDN Cache


PHASE 2: REQUEST EXECUTION (Request-time Resume Pass)
─────────────────────────────────────────────────────────────────────────────
Browser                   Edge CDN                    Serverless Worker (Origin)
   │                         │                                   │
(1)├─── GET /shop ──────────►│                                   │
   │                         ├── Immediate Shell Flush (TTFB)───►│
   │◄─── Chunk 1: Static Shell┤ [User perceives FCP in 30ms!]    │
   │    (with CartSkeleton)  │                                   │
   │                         │                      Resume from postpone point:
   │                         │                      const cookie = await cookies();
   │                         │                      const cart = await fetchCart();
   │                         │                                   │
(2)│                         │◄── Chunk 2: Dynamic Hole ─────────┤
   │◄── Replace Skeleton ────┤    Cart HTML + $RC()              │
   │    with live content    │                                   │

Partial Prerendering (PPR) Lifecycle

1. Build-time Static Shell Compilationbuild

Next.js builds the static page shell. When encountering dynamic APIs inside Suspense, it suspends execution via React.postpone() and persists the fallback skeleton.

2. Instant Edge Premature Flushnetwork

The user requests the page. Edge CDN immediately streams the cached Static Shell. The browser renders the interface structure within 20–30 ms.

3. Background Resumption (Resume Pass)server

The application server resumes execution strictly inside dynamic holes, reading incoming cookies and executing live database queries.

4. Streaming Chunk Deliverystream

Rendered dynamic HTML and RSC Flight Payloads stream through the open HTTP socket without full-page reloads.

5. Seamless DOM Replacementhydrate

Inline React client scripts swap out the skeleton for actual content, followed by selective hydration of interactive components.

CHECKPOINT #1

Concept Check: React Postpone API Mechanics

+15 XP

What happens during static compilation (next build) if a component in a route with experimental_ppr = true accesses await cookies() WITHOUT being wrapped in a <Suspense> boundary?

Syntax and API#

1. Configuring `next.config.ts`#

In modern Next.js releases, Partial Prerendering is activated through the experimental configuration block. The 'incremental' option enables adopting PPR incrementally on a per-route basis:

typescriptnext.config.ts

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  experimental: {
    // 'incremental' enables route-level PPR adoption via export const experimental_ppr = true
    ppr: 'incremental',
  },
};

export default nextConfig;

2. Enabling PPR on Route Segments#

To enable Partial Prerendering for a specific page or layout, export the experimental_ppr constant:

tsxapp/catalog/page.tsx

import { Suspense } from 'react';
import { StaticCatalogHeader } from '@/components/StaticCatalogHeader';
import { StaticProductGrid } from '@/components/StaticProductGrid';
import { PersonalizedCartWidget } from '@/components/PersonalizedCartWidget';
import { CartSkeleton } from '@/components/skeletons';

// Enable Partial Prerendering for this route segment
export const experimental_ppr = true;

export default function CatalogPage() {
  return (
    <main className="max-w-7xl mx-auto p-6 space-y-8">
      {/* Static section: compiled at build time (Build-time Prerender) */}
      <StaticCatalogHeader />

      <div className="flex justify-between items-start gap-8">
        {/* Static product catalog: served from Edge CDN instantly */}
        <div className="flex-1">
          <StaticProductGrid />
        </div>

        {/* Suspense boundary declares a dynamic hole */}
        <aside className="w-80">
          <Suspense fallback={<CartSkeleton />}>
            {/* Reads cookies() and evaluates during incoming request execution */}
            <PersonalizedCartWidget />
          </Suspense>
        </aside>
      </div>
    </main>
  );
}

3. What Marks a Component as Dynamic in Next.js 15+?#

A component is automatically classified as a dynamic hole if any of the following APIs are invoked in its render tree:

await cookies() from 'next/headers' (asynchronous in Next.js 15+)
await headers() from 'next/headers' (asynchronous in Next.js 15+)
The route searchParams prop (params: Promise<...>, searchParams: Promise<...>)
await connection() from 'next/server' (explicit trigger for deferred dynamic streaming)
Data fetching calls configured with fetch(..., { cache: 'no-store' })

Rendering Architecture Evolution: Streaming SSR vs Partial Prerendering (PPR)

Критерий	Streaming SSR	Partial Prerendering (PPR)
Where is the Shell generated?	Dynamically on the server for EVERY incoming request	At build time (Build-time) and cached globally on Edge CDN
Time to First Byte (TTFB)	Depends on Node.js/Serverless cold starts (100–300 ms)	Instantaneous (< 20–40 ms) straight from Edge CDN caches
Server Compute Overhead	High (server renders layouts and shells on every page visit)	Minimal (server evaluates ONLY components inside dynamic holes)
Dynamic Streaming Delivery	HTTP Chunked streaming initiated from scratch	Resumption (Resume) appending chunks to the static shell stream
Personalization Support	Full	Full (isolated through Suspense boundaries)

Practical Patterns#

Pattern 1: Isolating a Personalized Shopping Cart Dynamic Slot#

In e-commerce platforms, product catalogs remain identical across visitors, while user cart counters rely on session authentication cookies:

tsxcomponents/PersonalizedCartWidget.tsx (Dynamic Hole)

import { cookies } from 'next/headers';
import { db } from '@/lib/db';

export async function PersonalizedCartWidget() {
  // In Next.js 15+, cookies() is strictly asynchronous!
  const cookieStore = await cookies();
  const sessionToken = cookieStore.get('session_token')?.value;

  if (!sessionToken) {
    return <div className="text-sm text-text-muted">Cart is empty</div>;
  }

  // Executed exclusively during user request processing
  const cart = await db.cart.findUnique({
    where: { sessionToken },
    include: { items: true },
  });

  const count = cart?.items.reduce((acc, item) => acc + item.quantity, 0) ?? 0;

  return (
    <div className="flex items-center gap-2 px-3 py-1.5 rounded-lg border border-border bg-bg-elevated">
      <span className="text-sm font-medium text-text-primary">Cart Items:</span>
      <span className="font-mono font-bold text-accent-cyan">{count}</span>
    </div>
  );
}

Pattern 2: Explicit Deferred Streaming with Next.js 15+ `connection()`#

When a component does not read cookies but runs heavy analytics queries or fetches volatile market prices that should not be frozen during the build, use the connection() utility:

tsxcomponents/LiveStockTicker.tsx (Deferred Streaming)

import { connection } from 'next/server';
import { fetchLiveExchangeRates } from '@/lib/finance';

export async function LiveStockTicker() {
  // await connection() explicitly invokes React.postpone() at build time!
  // This instructs the compiler: do not attempt to run this code during the build,
  // execute it strictly when a real client connection is established.
  await connection();

  const rates = await fetchLiveExchangeRates();

  return (
    <div className="flex gap-4 text-xs font-mono py-1 overflow-x-auto text-text-muted">
      <span>USD/EUR: {rates.USDEUR}</span>
      <span>GBP/USD: {rates.GBPUSD}</span>
      <span>BTC/USD: {rates.BTCUSD}</span>
    </div>
  );
}

CHECKPOINT #2

Concept Check: The Request-Time Resume Pass

+15 XP

What does the application origin server execute when a request hits a PPR-enabled page whose Static Shell is already cached at the Edge CDN?

Common Pitfalls#

Ошибка: Unwrapped Dynamic APIs outside Suspense Crash the Static Shell

If you invoke asynchronous dynamic functions (await cookies(), await headers(), accessing searchParams) inside a Server Component that is not wrapped in a <Suspense> boundary while PPR is active, Next.js cannot generate a Static Shell and terminates next build with a build error.

Solution: Every component accessing dynamic request context must be enclosed in <Suspense fallback={<Skeleton />}>.

textCompiler Error when Missing Suspense Boundary

Error: Route /shop with `experimental_ppr` enabled accessed dynamic data without a Suspense boundary.

Ошибка: Reading searchParams in Root layout.tsx

Root layouts (layout.tsx) in Next.js intentionally do not have access to the searchParams prop. Layouts are persistent across subroute navigations to maximize caching efficiency within the Static Shell.

Solution: Access searchParams inside page.tsx or isolate search query handling in a Client Component using useSearchParams().

Ошибка: Cache-Control Header Conflicts on Reverse Proxies

Because a PPR response begins with a static CDN chunk and terminates with a dynamic server stream, misconfigured corporate proxies or reverse proxies (such as Nginx) may attempt to cache the entire response body, including private user cart data!

Solution: When self-hosting via Docker or custom Nginx setups, verify that reverse proxies support Transfer-Encoding: chunked and do not buffer responses marked with Cache-Control: private, no-cache, no-store.

Ошибка: Stream Fragmentation from Overly Granular Suspense Boundaries

Wrapping dozens of minute text nodes in individual Suspense boundaries fragments the HTTP response into hundreds of micro-chunks, increasing TCP and TLS packet overhead. Group related dynamic components into logical compound containers.

Interview Questions#

Interview Questions8 questions

Partial Prerendering (PPR) in Next.js: Hybrid Static and Dynamic Streaming

Why This Matters#

Mental Model#

Two-Phase Architecture of Partial Prerendering#

Syntax and API#

1. Configuring next.config.ts#

2. Enabling PPR on Route Segments#

3. What Marks a Component as Dynamic in Next.js 15+?#

Practical Patterns#

Pattern 1: Isolating a Personalized Shopping Cart Dynamic Slot#

Pattern 2: Explicit Deferred Streaming with Next.js 15+ connection()#

Common Pitfalls#

Ошибка: Unwrapped Dynamic APIs outside Suspense Crash the Static Shell

Ошибка: Reading searchParams in Root layout.tsx

Ошибка: Cache-Control Header Conflicts on Reverse Proxies

Ошибка: Stream Fragmentation from Overly Granular Suspense Boundaries

Interview Questions#

Why This Matters#

Mental Model#

Two-Phase Architecture of Partial Prerendering#

Syntax and API#

1. Configuring next.config.ts#

2. Enabling PPR on Route Segments#

3. What Marks a Component as Dynamic in Next.js 15+?#

Practical Patterns#

Pattern 1: Isolating a Personalized Shopping Cart Dynamic Slot#

Pattern 2: Explicit Deferred Streaming with Next.js 15+ connection()#

Common Pitfalls#

Ошибка: Unwrapped Dynamic APIs outside Suspense Crash the Static Shell

Ошибка: Reading searchParams in Root layout.tsx

Ошибка: Cache-Control Header Conflicts on Reverse Proxies

Ошибка: Stream Fragmentation from Overly Granular Suspense Boundaries

Interview Questions#

1. Configuring `next.config.ts`#

Pattern 2: Explicit Deferred Streaming with Next.js 15+ `connection()`#

1. Configuring `next.config.ts`#

Pattern 2: Explicit Deferred Streaming with Next.js 15+ `connection()`#