Beyond SSR vs SSG: Partial Prerendering (PPR) Explained with a Real-World Story

ynamic boundaries as data resolves.

Technical Implementation:

1. Static Shell Prerendering: Layout, navigation, and static content are compiled into HTML during the build phase and cached at the edge.
2. Suspense Boundaries as Stream Triggers: <Suspense> components act as streaming anchors. React sends the static HTML immediately, then appends dynamic chunks once async data resolves.
3. Progressive Hydration: The client attaches event listeners only to hydrated components, reducing main-thread blocking and improving Time to Interactive (TTI).
4. Next.js PPR Configuration: Enable via experimental.ppr = "incremental" in next.config.js. The framework automatically handles chunking, RSC (React Server Components) streaming, and fallback injection.

export default function ProductPage() {
  return (
    <main>

      {/* Static content (instant) */}
      <ProductNavigation />
      <ProductDetails />

      {/* Dynamic part (hole) */}
      <Suspense fallback={<PriceSkeleton />}>
        <DynamicUserPrice />
      </Suspense>

      {/* Another dynamic part */}
      <Suspense fallback={<RecommendationSkeleton />}>
        <RecommendedProducts />
      </Suspense>

    </main>
  );
}

Architecture Decisions:

• Component Granularity: Isolate data-dependent components to prevent slow queries from blocking the entire page.
• Fallback Sizing: Skeletons must match the exact dimensions of the dynamic component to maintain layout stability.
• Data Fetching Strategy: Use server components for initial data streams; client components only when interactivity or browser APIs are required.

Pitfall Guide

1. Over-Fragmenting Suspense Boundaries: Creating too many isolated boundaries increases HTTP chunk overhead and triggers multiple network round-trips. Best Practice: Group related dynamic data under a single boundary. Use parallel data fetching (Promise.all) to resolve chunks in one stream.
2. Hydration Mismatch on Fallbacks: If the skeleton UI dimensions or DOM structure differ from the final component, React throws hydration warnings and causes visual jumps. Best Practice: Use fixed-width/height CSS for skeletons. Ensure the fallback DOM tree mirrors the expected final structure.
3. Missing Error Boundaries: Streaming can fail mid-response. Without error isolation, a single failed dynamic chunk can crash the entire page. Best Practice: Wrap dynamic boundaries in React Error Boundaries (@next/error or custom componentDidCatch) with graceful degradation or retry logic.
4. Cache Invalidation Blind Spots: Static shells are aggressively cached at the CDN. If dynamic data relies on stale cache keys, users see outdated information. Best Practice: Implement stale-while-revalidate (SWR) or on-demand revalidation for dynamic data sources. Use revalidate tags in Next.js to invalidate specific chunks without full rebuilds.
5. Blocking I/O in Streaming Components: PPR relies on non-blocking streams. Synchronous database calls, heavy computations, or unhandled promise rejections inside streaming components will block the HTML chunk and defeat the purpose. Best Practice: Always use async data fetching with explicit timeout handling. Fail fast and trigger fallbacks if data exceeds SLA thresholds.
6. SEO Misalignment with Critical Content: Search engines index the initial static shell. If primary SEO content (titles, pricing, availability) is hidden behind Suspense, it may be deprioritized or missed by crawlers. Best Practice: Keep meta tags, canonical URLs, and primary content static. Isolate only user-specific, real-time, or personalization data in dynamic holes.

Deliverables

• 📘 PPR Architecture Blueprint: Decision matrix for mapping UI components to rendering strategies (Static vs. Suspense-streamed vs. Client-interacted). Includes data dependency mapping templates and chunking guidelines.
• ✅ Pre-Deployment Validation Checklist: 12-point audit covering Suspense boundary placement, fallback dimension parity, error boundary coverage, cache strategy alignment, SEO crawl verification, and streaming latency thresholds.
• ⚙️ Configuration Templates:
  • next.config.js PPR incremental flags & React 18 streaming settings
  • Reusable <SuspenseWrapper> component with built-in error handling & analytics tracking
  • CSS-in-JS skeleton grid templates matching common UI patterns (cards, tables, pricing modules)