Partial Prerendering (PPR)

Serve a static shell instantly and stream dynamic content into Suspense holes -- the best of static and dynamic rendering.

Recipe

Quick-reference recipe card -- copy-paste ready.

// next.config.ts -- enable PPR
import type { NextConfig } from "next";
 
const config: NextConfig = {
  experimental: {
    ppr: true, // or "incremental" for per-route opt-in
  },
};
 
export default config;

// app/page.tsx -- static shell with dynamic holes
import { Suspense } from "react";
import { cookies } from "next/headers";
 
export default function Page() {
  return (
    <main>
      <h1>Welcome to the Store</h1>  {/* Static shell */}

When to reach for this: You have a page where most content is static (product info, marketing copy) but a small part depends on the request (user session, cart, personalization).

Working Example

// next.config.ts
import type { NextConfig } from "next";
 
const config: NextConfig = {
  experimental: {
    ppr: "incremental", // opt in per route
  },
};
 
export default config;

// app/products/[slug]/page.tsx
import { Suspense } from "react";
import { cookies } from "next/headers";
import { db } from "@/lib/db";
import { AddToCartButton } from "./add-to-cart";
 
// Opt this route into PPR
export const experimental_ppr = true;

What this demonstrates:

• Enabling PPR incrementally per route with experimental_ppr = true
• The product info (name, price, description, image) is the static shell -- prerendered at build time and served from the CDN
• Personalized recommendations and recently viewed products are dynamic holes -- they use cookies() and stream in at request time
• Skeleton fallbacks appear instantly as part of the static shell
• generateStaticParams pre-renders product pages at build time

Deep Dive

How It Works

• With PPR, Next.js prerenders the static parts of a page at build time, including Suspense fallbacks. The result is a complete HTML shell stored on the CDN.
• When a request arrives, the static shell is sent immediately (edge latency). The server then resumes rendering the dynamic portions (components that call cookies(), headers(), searchParams, or cache: "no-store").
• Dynamic content is streamed into the Suspense boundaries, replacing the fallback skeletons as each boundary resolves.
• The key insight: Suspense boundaries define the static/dynamic split. Everything outside a Suspense boundary with a dynamic child is part of the static shell. Everything inside is a dynamic hole.
• PPR combines the performance of static generation (instant TTFB from CDN) with the flexibility of dynamic rendering (personalized, request-time content).

Variations

Incremental adoption (per-route opt-in):

// next.config.ts
export default { experimental: { ppr: "incremental" } };
 
// Only this page uses PPR
// app/products/[slug]/page.tsx
export const experimental_ppr = true;

All routes PPR (global):

// next.config.ts
export default { experimental: { ppr: true } };
// All routes automatically use PPR

Multiple dynamic holes with independent data sources:

export default function Page() {
  return (
    <main>
      <StaticNav />
      <StaticHero />
 
      {/* Each Suspense boundary is an independent dynamic hole */}
      <Suspense fallback={<UserBarSkeleton />}>
        <UserBar

TypeScript Notes

// Per-route PPR opt-in export
export const experimental_ppr: boolean = true;
 
// next.config.ts type
import type { NextConfig } from "next";
const config: NextConfig = {
  experimental: {
    ppr: true | "incremental",

Gotchas

• PPR is experimental -- As of Next.js 15/16, PPR requires the experimental.ppr flag. The API may change. Fix: Pin your Next.js version and test thoroughly before production use.

• Suspense boundary placement determines the split -- If you forget to wrap a dynamic component in Suspense, the entire page becomes dynamic. Fix: Always wrap components that use dynamic functions in a <Suspense> boundary.

• Fallback quality matters -- The Suspense fallback is part of the static shell and is visible to all users instantly. A poor fallback creates a bad first impression. Fix: Use well-designed skeletons that match the shape and size of the real content.

• Dynamic holes add server cost -- Each dynamic hole requires server computation at request time. Too many dynamic holes negate the CDN benefits. Fix: Consolidate related dynamic data into fewer Suspense boundaries.

• No PPR on Edge Runtime for all providers -- PPR requires the hosting platform to support streaming and the postpone API. Fix: Verify your deployment platform supports PPR (Vercel supports it natively).

• Client Components in the static shell still ship JavaScript -- PPR makes the HTML static, but Client Components still hydrate on the client. Fix: Keep the static shell composed primarily of Server Components for minimal JavaScript.

Alternatives

FAQs

<Suspense fallback={<UserBarSkeleton />}>
  <UserBar />       {/* cookies() */}
</Suspense>
<Suspense fallback={<PricingSkeleton />}>
  <LivePricing />   {/* cache: "no-store" */}

// next.config.ts
export default { experimental: { ppr: "incremental" } };
 
// app/products/[slug]/page.tsx
export const experimental_ppr = true;

export const experimental_ppr: boolean = true;

Related

• Static vs Dynamic -- Understanding rendering modes
• Streaming -- How Suspense enables progressive rendering
• Server Components -- The building blocks of the static shell
• Cookies & Headers -- Dynamic functions that create dynamic holes