nextjs-ppr-patterns

Next.js 16 Partial Prerendering Patterns

Partial Prerendering (PPR) for the Next.js 16 App Router under the Cache Components model — the decisions PPR forces and how to settle them, written so an agent applies them while writing or reviewing code. Contains 21 rules across 6 categories, ordered from easy to complex: enable PPR → understand the static/dynamic boundary → cache → handle runtime data → compose whole pages → build forms and wizards. Each rule corrects a specific wrong default of a model defaulting to Next.js 14/15; there is no rule for things the model already gets right.

Version-specific. This skill targets Next.js 16 (PPR via cacheComponents, React 19.2). The Next.js 14/15 experimental.ppr flag and export const experimental_ppr route export were removed — see setup-enable-cache-components. For migrating an existing app, see the migration guide.

Write, then verify. These rules are for authoring PPR; they can't tell you what actually rendered. To empirically deconstruct the boundary — diff the static shell against the hydrated DOM to find the dynamic holes, locate the 'use client' islands, measure loading, and explain why a route is dynamic — drive next build and a real browser per _debug-boundaries.md.

When to Apply

• Building or reviewing a Next.js 16 page that mixes static chrome with personalized, real-time, or per-request content
• Enabling or migrating PPR (cacheComponents), or seeing dead experimental.ppr / experimental_ppr code
• Deciding where <Suspense> boundaries go, or debugging an Uncached data was accessed outside of <Suspense> build error
• Adding 'use cache', cacheLife, cacheTag, or choosing updateTag / revalidateTag / refresh after a mutation
• Composing forms, multi-step wizards, dashboards, or streaming server data into interactive Client Components
• Empirically verifying or debugging what actually rendered — which parts are in the static shell vs streamed, where the CSR/SSR boundary is, and why a route went dynamic