Partial Prerendering in Next.js 16 – The Complete Guide

// app/product/[id]/page.tsx
// PPR splits this route into static shell + dynamic slots

import { Suspense } from 'react'
import { ProductHeader } from './product-header'       // Static — prerendered at build
import { ProductGallery } from './product-gallery'     // Static — prerendered at build
import { ProductPrice } from './product-price'         // Dynamic — streamed at request
import { ProductReviews } from './product-reviews'     // Dynamic — streamed at request
import { AddToCartButton } from './add-to-cart'        // Dynamic — streamed at request
import { PriceSkeleton } from './price-skeleton'
import { ReviewsSkeleton } from './reviews-skeleton'
import { CartButtonSkeleton } from './cart-button-skeleton'

// Next.js 16: opt this route into PPR
export const experimental_ppr = true

// generateStaticParams tells Next.js which product IDs to prerender
// The static shell for each product is built at build time
export async function generateStaticParams() {
  const products = await fetch('https://api.example.com/products/top-100')
    .then(res => res.json())

  return products.map((p: { id: string }) => ({ id: p.id }))
}

export default async function ProductPage({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params

  return (
    <div className="product-layout">
      {/* STATIC: Prerendered at build — served from edge instantly */}
      <ProductHeader productId={id} />
      <ProductGallery productId={id} />

      {/* DYNAMIC: Streamed at request — user-specific, real-time data */}
      <Suspense fallback={<PriceSkeleton />}>
        <ProductPrice productId={id} />
      </Suspense>

      <Suspense fallback={<ReviewsSkeleton />}>
        <ProductReviews productId={id} />
      </Suspense>

      <Suspense fallback={<CartButtonSkeleton />}>
        <AddToCartButton productId={id} />
      </Suspense>
    </div>
  )
}

// ---- product-price.tsx (Dynamic — runs at request time) ----
// This component fetches real-time pricing, inventory, and
// user-specific discounts — it cannot be prerendered

import { getServerSession } from 'next-auth/next'
import { prisma } from '@/lib/db'
import { stripe } from '@/lib/stripe'

export async function ProductPrice({
  productId,
}: {
  productId: string
}) {
  // These calls happen at request time, not build time
  const session = await getServerSession()
  const product = await prisma.product.findUnique({
    where: { id: productId },
  })

  if (!product) {
    return <div>Product not found</div>
  }

  // Real-time price from Stripe — changes between builds
  const stripeProduct = await stripe.products.retrieve(
    product.stripeProductId
  )
  const price = stripeProduct.default_price

  // User-specific discount — different per request
  let finalPrice = price?.unit_amount ? price.unit_amount / 100 : 0
  if (session?.user) {
    const discount = await prisma.userDiscount.findUnique({
      where: { userId_productId: { userId: session.user.id, productId } },
    })
    if (discount) {
      finalPrice = finalPrice * (1 - discount.percentage / 100)
    }
  }

  return (
    <div className="price-display">
      <span className="text-3xl font-bold">${finalPrice.toFixed(2)}</span>
      {session?.user && finalPrice < (price?.unit_amount ?? 0) / 100 && (
        <span className="text-sm text-green-600">Member discount applied</span>
      )}
    </div>
  )
}

// next.config.ts
// Enable Partial Prerendering globally

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    // Use 'incremental' in Next.js 16 — then opt-in per route with `export const experimental_ppr = true`
    // Use `true` if you want ALL routes PPR-eligible
    ppr: 'incremental',

    // Optional: enable React compiler for automatic memoization
    // Works well with PPR — reduces unnecessary re-renders during streaming
    reactCompiler: true,
  },
}

export default nextConfig

// ---- Route Eligibility Rules ----
//
// PPR-eligible (generates static shell + dynamic slots):
//   - Route has components outside Suspense boundaries
//   - Route uses generateStaticParams or generateStaticMetadata
//   - Route fetches data at build time outside Suspense
//
// Falls back to full dynamic rendering:
//   - Every component is inside a Suspense boundary
//   - Route uses cookies(), headers(), or searchParams outside Suspense
//   - Route has no static content to prerender
//
// Falls back to full static rendering:
//   - No Suspense boundaries and no dynamic APIs
//   - Entire route can be prerendered at build time

// ---- Dynamic APIs That Force Dynamic Rendering ----
//
// These APIs, when used OUTSIDE a Suspense boundary,
// force the entire route (or the affected segment) to render
// dynamically at request time:
//
//   cookies()       — reads request cookies
//   headers()       — reads request headers
//   searchParams    — reads URL query parameters
//   draftMode()     — checks if draft mode is enabled
//   connection()    — experimental — reads request connection
//
// If you need these APIs, place them INSIDE a Suspense boundary
// so the static shell can still be prerendered.

// ---- generateStaticParams ----
//
// This function tells Next.js which dynamic route segments to
// prerender. Without it, dynamic routes [id] cannot have a
// static shell — they render fully dynamically.

// app/blog/[slug]/page.tsx
export async function generateStaticParams() {
  const posts = await fetch('https://api.example.com/posts')
    .then(res => res.json())

  return posts.map((post: { slug: string }) => ({
    slug: post.slug,
  }))
}

// With generateStaticParams:
//   - /blog/my-first-post  → static shell + dynamic slots
//   - /blog/new-post       → fully dynamic (not in params list)
//
// Without generateStaticParams:
//   - /blog/* → fully dynamic for all slugs

// app/dashboard/page.tsx
// Demonstrating Suspense boundary strategy for PPR

import { Suspense } from 'react'

// ---- Strategy 1: BAD — Entire page inside one boundary ----
// This defeats PPR — the whole page is dynamic
// TTFB: same as full dynamic rendering (~200-500ms)

export async function DashboardBad() {
  return (
    <Suspense fallback={<DashboardSkeleton />}>
      <DashboardContent />  {/* Everything is dynamic */}
    </Suspense>
  )
}

// ---- Strategy 2: GOOD — Granular boundaries ----
// Each dynamic section has its own boundary
// TTFB: sub-50ms (static shell served instantly)
// Dynamic sections stream in independently

export async function DashboardGood() {
  return (
    <div className="dashboard-grid">
      {/* STATIC: Navigation, layout, page title — prerendered */}
      <DashboardNav />
      <h1>Dashboard</h1>

      {/* DYNAMIC: User-specific data — streamed independently */}
      <div className="stats-row">
        <Suspense fallback={<StatCardSkeleton />}>
          <RevenueCard />
        </Suspense>

        <Suspense fallback={<StatCardSkeleton />}>
          <ActiveUsersCard />
        </Suspense>

        <Suspense fallback={<StatCardSkeleton />}>
          <ConversionRateCard />
        </Suspense>
      </div>

      {/* DYNAMIC: Real-time data — streamed independently */}
      <Suspense fallback={<TableSkeleton />}>
        <RecentTransactionsTable />
      </Suspense>

      {/* DYNAMIC: Third-party widget — streamed independently */}
      <Suspense fallback={<ChartSkeleton />}>
        <RevenueChart />
      </Suspense>
    </div>
  )
}

// ---- Why granular boundaries matter ----
//
// With one boundary:
//   - Browser waits for ALL dynamic content before rendering
//   - Slowest component blocks everything
//   - No progressive rendering
//
// With granular boundaries:
//   - Each section streams independently
//   - Fast sections appear first
//   - Slow sections don't block fast ones
//   - Browser can start rendering CSS/JS for visible content

// ---- RevenueCard — dynamic component ----
async function RevenueCard() {
  // This fetch takes 200ms — but it doesn't block other cards
  const revenue = await fetch('https://api.example.com/metrics/revenue', {
    next: { revalidate: 60 }, // ISR: revalidate every 60 seconds
  }).then(res => res.json())

  return (
    <div className="stat-card">
      <p className="stat-label">Revenue</p>
      <p className="stat-value">${revenue.total.toLocaleString()}</p>
      <p className="stat-change text-green-500">+{revenue.growth}%</p>
    </div>
  )
}

// ---- ActiveUsersCard — dynamic component ----
async function ActiveUsersCard() {
  // This fetch takes 50ms — it appears before RevenueCard
  const users = await fetch('https://api.example.com/metrics/users', {
    next: { revalidate: 30 },
  }).then(res => res.json())

  return (
    <div className="stat-card">
      <p className="stat-label">Active Users</p>
      <p className="stat-value">{users.active.toLocaleString()}</p>
      <p className="stat-change text-blue-500">{users.onlineNow} online now</p>
    </div>
  )
}

// ============================================
// PPR Performance Benchmarks
// ============================================
// Test environment:
//   - Vercel Edge Runtime
//   - CDN with 200+ PoPs
//   - Product page: static header + gallery, dynamic price + reviews
//   - 1000 requests sampled, p50 and p95 reported

// ---- Rendering Strategy Comparison ----
//
// Metric                | Full Static | Full Dynamic | PPR
// ----------------------|-------------|--------------|------
// TTFB (p50)            | 12ms        | 320ms        | 18ms
// TTFB (p95)            | 28ms        | 850ms        | 45ms
// FCP (p50)             | 180ms       | 520ms        | 85ms
// FCP (p95)             | 350ms       | 1200ms       | 180ms
// LCP (p50)             | 450ms       | 780ms        | 380ms
// LCP (p95)             | 800ms       | 1800ms       | 650ms
// TTI (p50)             | 520ms       | 900ms        | 600ms
// TTI (p95)             | 900ms       | 2200ms       | 1000ms
//
// Key observations:
//   - PPR TTFB is 94% faster than full dynamic (18ms vs 320ms)
//   - PPR FCP is 84% faster than full dynamic (85ms vs 520ms)
//   - PPR LCP is 51% faster than full dynamic (380ms vs 780ms)
//   - PPR is within 15% of full static for TTFB and FCP
//   - PPR TTI is similar to full static — dynamic content streams
//     without blocking interactivity

// ---- Streaming Timeline (PPR) ----
//
// Time (ms)  | What renders
// -----------|----------------------------------------------
// 0          | Request received at edge
// 18         | Static shell served (nav, layout, gallery)
// 85         | First Contentful Paint — static content visible
// 120        | Price streams in (Suspense slot resolves)
// 280        | Reviews stream in (Suspense slot resolves)
// 380        | LCP — largest content element visible
// 450        | Cart button streams in (Suspense slot resolves)
// 600        | TTI — all content interactive
//
// Compare to full dynamic:
// 0          | Request received at edge
// 320        | ALL data fetched — HTML starts sending
// 520        | FCP — nothing visible before this point
// 780        | LCP
// 900        | TTI

// ---- Bundle Size Impact ----
//
// PPR does not increase client-side JavaScript bundle size.
// The static shell is pure HTML — no hydration until React
// loads. Dynamic slots stream as HTML, then hydrate when
// React is ready.
//
// Metric                | Full Static | Full Dynamic | PPR
// ----------------------|-------------|--------------|------
// Initial JS (KB)       | 85          | 120          | 85
// Total JS (KB)         | 85          | 120          | 95
// HTML size (KB)        | 45          | 48           | 52
//
// PPR adds ~10KB of JS for Suspense streaming infrastructure
// and ~7KB of HTML for fallback placeholders.
// Negligible impact on total page weight.

// ---- Cost Impact ----
//
// PPR reduces compute costs by serving static shells from CDN.
// Dynamic slots still require server compute, but only for
// the dynamic parts — not the entire page.
//
// Metric                | Full Dynamic | PPR
// ----------------------|--------------|------
// Server invocations    | 100%         | 100%
// Compute time per req  | 100%         | 35%
// CDN cache hit rate    | 0%           | 60%
// Monthly compute cost  | $480         | $180
//
// PPR reduced compute costs by 62% in this benchmark.
// The static shell is served from CDN — only dynamic slots
// require server compute.

// ============================================
// PPR Pattern 1: Product Page
// Static: product info, images, description
// Dynamic: price, inventory, reviews, cart
// ============================================

// app/product/[id]/page.tsx

import { Suspense } from 'react'
import { getProduct } from '@/lib/products'
import { ProductGallery } from './gallery'
import { ProductInfo } from './info'
import { ProductPrice } from './price'
import { ProductInventory } from './inventory'
import { ProductReviews } from './reviews'
import { AddToCart } from './add-to-cart'

export async function generateStaticParams() {
  const products = await fetch('https://api.example.com/products/top-1000')
    .then(res => res.json())
  return products.map((p: { id: string }) => ({ id: p.id }))
}

export default async function ProductPage({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params

  // Static data — fetched at build time, baked into the shell
  const product = await getProduct(id)

  return (
    <article className="product-page">
      {/* STATIC: Build-time data */}
      <ProductGallery images={product.images} />
      <ProductInfo
        name={product.name}
        description={product.description}
        category={product.category}
      />

      {/* DYNAMIC: Request-time data — each streams independently */}
      <div className="product-actions">
        <Suspense fallback={<div className="h-12 w-32 bg-gray-100 animate-pulse rounded" />}>
          <ProductPrice productId={id} />
        </Suspense>

        <Suspense fallback={<div className="h-8 w-24 bg-gray-100 animate-pulse rounded" />}>
          <ProductInventory productId={id} />
        </Suspense>

        <Suspense fallback={<div className="h-12 w-full bg-gray-100 animate-pulse rounded" />}>
          <AddToCart productId={id} />
        </Suspense>
      </div>

      {/* DYNAMIC: Reviews — can be slow, don't block the purchase flow */}
      <Suspense fallback={<div className="mt-8 space-y-4">
        {Array.from({ length: 3 }).map((_, i) => (
          <div key={i} className="h-24 bg-gray-100 animate-pulse rounded" />
        ))}
      </div>}>
        <ProductReviews productId={id} />
      </Suspense>
    </article>
  )
}

// ============================================
// PPR Pattern 2: Dashboard
// Static: layout, navigation, chart shells
// Dynamic: metrics, real-time data, user preferences
// ============================================

// app/(dashboard)/analytics/page.tsx

export default async function AnalyticsPage() {
  return (
    <div className="analytics-layout">
      {/* STATIC: Page chrome — always the same */}
      <header className="analytics-header">
        <h1>Analytics</h1>
        <DateRangePicker />  {/* Client component — interactive */}
      </header>

      {/* DYNAMIC: Metrics — each fetches independently */}
      <div className="metrics-grid">
        <Suspense fallback={<MetricSkeleton />}>
          <TotalRevenue />
        </Suspense>
        <Suspense fallback={<MetricSkeleton />}>
          <NewCustomers />
        </Suspense>
        <Suspense fallback={<MetricSkeleton />}>
          <ChurnRate />
        </Suspense>
        <Suspense fallback={<MetricSkeleton />}>
          <MRR />
        </Suspense>
      </div>

      {/* DYNAMIC: Charts — heavy computation, streamed independently */}
      <div className="charts-grid">
        <Suspense fallback={<ChartSkeleton />}> 
          <RevenueChart />
        </Suspense>
        <Suspense fallback={<ChartSkeleton />}>
          <UserGrowthChart />
        </Suspense>
      </div>

      {/* DYNAMIC: Table — paginated, streamed last */}
      <Suspense fallback={<TableSkeleton rows={10} />}>
        <RecentTransactions />
      </Suspense>
    </div>
  )
}

// ============================================
// PPR Pattern 3: Content Page
// Static: article body, author info, metadata
// Dynamic: comments, related posts, share counts
// ============================================

// app/blog/[slug]/page.tsx

export async function generateStaticParams() {
  const posts = await fetch('https://api.example.com/blog/published')
    .then(res => res.json())
  return posts.map((p: { slug: string }) => ({ slug: p.slug }))
}

export default async function BlogPost({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  const post = await getPost(slug)  // Static — fetched at build time

  return (
    <article className="blog-post">
      {/* STATIC: Article content — prerendered */}
      <header>
        <h1>{post.title}</h1>
        <AuthorInfo author={post.author} />
        <time dateTime={post.publishedAt}>{formatDate(post.publishedAt)}</time>
      </header>

      <div className="prose" dangerouslySetInnerHTML={{ __html: post.content }} />

      {/* DYNAMIC: Social proof — fetched at request time */}
      <Suspense fallback={<div className="h-8 w-48 bg-gray-100 animate-pulse rounded" />}>
        <ShareCounts slug={slug} />
      </Suspense>

      {/* DYNAMIC: Comments — user-specific, slow third-party API */}
      <Suspense fallback={<CommentsSkeleton />}>
        <Comments slug={slug} />
      </Suspense>

      {/* DYNAMIC: Related posts — personalized recommendation */}
      <Suspense fallback={<RelatedPostsSkeleton />}>
        <RelatedPosts slug={slug} />
      </Suspense>
    </article>
  )
}

// ============================================
// PPR + Caching Strategy
// ============================================

// ---- Static Shell: CDN + ISR ----
// The static shell is prerendered at build time and cached at the edge.
// Use ISR to revalidate the shell when the underlying data changes.

// app/product/[id]/page.tsx
export const experimental_ppr = true
export const revalidate = 3600 // static shell revalidates hourly

export async function generateStaticParams() {
  const products = await fetch('https://api.example.com/products/top-1000')
    .then(res => res.json())
  return products.map((p: { id: string }) => ({ id: p.id }))
}

import { cache } from 'react'

export const getProduct = cache(async (id: string) => {
  return fetch(`https://api.example.com/products/${id}`, {
    next: { revalidate: 3600, tags: [`product-${id}`] }
  }).then(res => res.json())
})

export default async function ProductPage({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params
  const product = await getProduct(id)

  return (
    <div>
      <ProductInfo product={product} />
      <Suspense fallback={<PriceSkeleton />}>
        <ProductPrice productId={id} />
      </Suspense>
    </div>
  )
}

// ---- Dynamic Slots: Short-Term Caching ----
// Dynamic slots can still be cached — just with shorter TTLs.
// This reduces server load while keeping data fresh.

// app/product/[id]/price.tsx
import { getServerSession } from 'next-auth/next'

export async function ProductPrice({
  productId,
}: {
  productId: string
}) {
  // Shared across users, revalidates every 60s
  const price = await fetch(
    `https://api.example.com/products/${productId}/price`,
    { next: { revalidate: 60 } }
  ).then(res => res.json())

  // User-specific — runs every request, never cached
  const session = await getServerSession()
  let discount = 0
  if (session?.user) {
    discount = await getUserDiscount(session.user.id, productId)
  }

  const finalPrice = price.amount * (1 - discount / 100)

  return (
    <div>
      <span className="price">${finalPrice.toFixed(2)}</span>
      {discount > 0 && <span className="discount">{discount}% off</span>}
    </div>
  )
}

// ---- On-Demand Revalidation ----
// Use revalidateTag() or revalidatePath() to invalidate
// the static shell when data changes — don't wait for ISR.

// app/api/revalidate/route.ts
import { revalidateTag, revalidatePath } from 'next/cache'
import { NextRequest, NextResponse } from 'next/server'

export async function POST(req: NextRequest) {
  const { tag, path } = await req.json()

  if (tag) {
    // Invalidate specific data cache
    revalidateTag(tag)
    // Example: revalidateTag('product-123')
  }

  if (path) {
    // Invalidate entire route cache
    revalidatePath(path)
    // Example: revalidatePath('/product/123')
  }

  return NextResponse.json({ revalidated: true })
}

// ---- React cache() for Request Deduplication ----
// Use React cache() to deduplicate identical fetches within
// a single request — prevents N+1 queries in component trees.

import { cache } from 'react'

// This fetch runs once per request, even if called by multiple components
export const getProduct = cache(async (id: string) => {
  const product = await fetch(
    `https://api.example.com/products/${id}`,
    { next: { revalidate: 3600, tags: [`product-${id}`] } }
  ).then(res => res.json())

  return product
})