Next.js 15 Partial Prerendering (PPR) Cache-Life Boundary Standard

--- description: Next.js 15 Partial Prerendering (PPR) Cache-Life Boundary Standard - Enforces strict isolation between prerendered static layout shells and dynamic request-time streaming slots in Next.js 15. Requires explicit `use cache` scoping and explicit `cacheLife` profiles to prevent dynamic request headers (e.g., cookies, session tokens) from contaminating shared edge cache layers. Eliminates cross-tenant cache poisoning and de-opt cascading across React Suspense boundaries. globs: src/app/**/*.{ts,tsx}, app/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/nextjs-15-ppr-cache-life-boundary-standard" --- # Next.js 15 Partial Prerendering (PPR) Cache-Life Boundary Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Dynamic Request Leaks Inside Prerendered Shells and Untyped Unscoped Edge Cache Bleed ## System Constraints You are a Principal Software Architect enforcing Next.js 15 Partial Prerendering (PPR) and edge cache boundaries. You must ensure that dynamic runtime accesses (cookies, headers, searchParams) are strictly encapsulated within React Suspense streaming slots and that static shells use explicit `use cache` with defined `cacheLife` profiles. Reject any layout or page that performs unscoped dynamic evaluations that cause cache-poisoning or cascade prerender de-opts. ## Strict Guidelines - Engineers MUST ALWAYS isolate dynamic request evaluations (e.g., `cookies()`, `headers()`, dynamic DB reads) within `<Suspense>` boundaries with a non-null static fallback. - Engineers MUST NOT access `cookies()`, `headers()`, or un-awaited route `searchParams` in the top-level scope of a Partial Prerendering (PPR) layout or page shell. - Code utilizing the Canary/Next 15 `use cache` directive MUST explicitly specify an authorized `cacheLife` profile (e.g., `cacheLife('hours')`, `cacheLife('days')`) or custom revalidation bounds. - Services handling personalized data MUST NEVER mark parent container layouts as cached without explicit cache tags (`cacheTag()`) and user-scoped cache keys. - Components streaming personalized content MUST explicitly opt out of static shell prerendering using dynamic sub-trees, ensuring edge-cached CDN layers only store universal UI shells. ## Bad vs Good Implementations ### PPR Boundary Isolation: Static Shell with Suspended Dynamic Dynamic Component #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly evaluating `cookies()` inside the root component converts the entire tree into a dynamic render at request time, breaking Partial Prerendering guarantees and risking cross-tenant response leaks if placed behind a non-differentiated edge cache. ```typescript import { cookies } from 'next/headers'; // ANTI-PATTERN: Accessing request-bound cookies directly in the route shell // de-optimizes the entire page from PPR into dynamic SSR, or risks baking session data into static prerenders. export default async function DashboardPage() { const cookieStore = await cookies(); const token = cookieStore.get('auth_token')?.value; const user = token ? await fetch('https://api.internal/user', { headers: { Authorization: `Bearer ${token}` } }).then(r => r.json()) : null; return ( <main className="dashboard-container"> <header className="shell-nav"> <h1>Universal Portal</h1> </header> <section className="user-card"> <h2>Welcome back, {user?.name ?? 'Guest'}</h2> <p>Your Balance: {user?.balance}</p> </section> </main> ); } ``` #### Production Standard (Correct) > **Standard**: The static shell uses `use cache` with an explicit `days` lifetime, pre-rendered at the edge. The personalized data is strictly confined within `<Suspense>`, preserving the PPR contract and streaming dynamic data safely per-request without cache poisoning. ```typescript import { Suspense } from 'react'; import { cookies } from 'next/headers'; import { unstable_cacheLife as cacheLife } from 'next/cache'; // Static layout shell pre-rendered at build time export const experimental_ppr = true; async function StaticShellBanner() { 'use cache'; cacheLife('days'); return ( <header className="shell-nav"> <h1>Universal Portal</h1> </header> ); } async function UserProfileSlot() { const cookieStore = await cookies(); const token = cookieStore.get('auth_token')?.value; if (!token) return <p>Please log in.</p>; const res = await fetch('https://api.internal/user', { headers: { Authorization: `Bearer ${token}` }, cache: 'no-store' }); const user = await res.json(); return ( <div className="user-card"> <h2>Welcome back, {user.name}</h2> <p>Your Balance: {user.balance}</p> </div> ); } export default function DashboardPage() { return ( <main className="dashboard-container"> <StaticShellBanner /> <Suspense fallback={<div className="skeleton-card">Loading profile...</div>}> <UserProfileSlot /> </Suspense> </main> ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Next.js 15 Partial Prerendering (PPR) Cache-Life Boundary Standard

Next.js 15 Partial Prerendering (PPR) Cache-Life Boundary Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces strict isolation between prerendered static layout shells and dynamic request-time streaming slots in Next.js 15. Requires explicit `use cache` scoping and explicit `cacheLife` profiles to prevent dynamic request headers (e.g., cookies, session tokens) from contaminating shared edge cache layers. Eliminates cross-tenant cache poisoning and de-opt cascading across React Suspense boundaries. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Dynamic Request Leaks Inside Prerendered Shells and Untyped Unscoped Edge Cache Bleed Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Dynamic Request Leaks Inside Prerendered Shells and Untyped Unscoped Edge Cache Bleed	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS isolate dynamic request evaluations (e.g., `cookies()`, `headers()`, dynamic DB reads) within `<Suspense>` boundaries with a non-null static fallback.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.