Mandatory Suspense Encapsulation for Next.js 15 Dynamic IO and PPR

--- description: Mandatory Suspense Encapsulation for Next.js 15 Dynamic IO and PPR - Enforces that any uncached runtime data access, dynamic APIs (headers, cookies, searchParams), or uncached database operations under Next.js 15 dynamicIO/Partial Prerendering (PPR) are encapsulated within dedicated, isolated React Suspense boundaries. Prevents runtime de-optimization cascades where an uncached operation at a page or root layout level bubbles up and forces an entire static shell into dynamic runtime execution. 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-dynamic-io-ppr-suspense-boundaries" --- # Mandatory Suspense Encapsulation for Next.js 15 Dynamic IO and PPR > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Leaking Dynamic IO and Runtime APIs to Page-Level Shells De-optimizing Static Partial Prerendering ## System Constraints You are a Principal Frontend Architect enforcing Next.js 15 Dynamic IO (`experimental.dynamicIO: true`) and Partial Prerendering (PPR) architectural invariants. Next.js 15 treats dynamic IO—such as headers(), cookies(), uncached fetch(), connection(), or direct unmemoized ORM calls—as dynamic branches. If accessed outside an explicit <Suspense> boundary, the build will fail or the entire page shell will de-optimize to dynamic execution at request time. You must strictly enforce encapsulating dynamic data access inside isolated child components wrapped by <Suspense> with deterministic fallback UI. ## Strict Guidelines - Engineers MUST ALWAYS isolate uncached dynamic IO operations (such as `cookies()`, `headers()`, database queries, or uncached third-party SDK calls) into dedicated async Server Components wrapped within an explicit `<Suspense fallback={<Skeleton />}>` boundary. - Engineers MUST NOT call dynamic runtime functions (`cookies()`, `headers()`, `connection()`) or await dynamic route parameters directly in the top-level Page or Layout export component without an immediate Suspense wrapper. - Root and segment layouts MUST remain strictly static shells; layouts MUST NEVER directly await dynamic data fetches that prevent shell pre-rendering under PPR. - Code SHOULD utilize `'use cache'` explicitly when data across requests can be memoized, reserving dynamic execution solely for personalized or real-time boundaries. - Components NEVER pass un-awaited dynamic promises from layout or page roots into synchronous JSX children without either streaming them with `use()` inside a Suspense boundary or awaiting them directly inside an encapsulated async component child. - Engineers MUST provide deterministic, layout-stable fallback components for every `<Suspense>` boundary to prevent cumulative layout shift (CLS) during streaming partial prerender hydration. ## Bad vs Good Implementations ### Encapsulating Dynamic Headers & User Cart within Suspense Boundary #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Accessing `await cookies()` and issuing an un-cached DB read directly inside the `Page` component forces the Next.js 15 PPR compiler to de-optimize the static shell (`header`, layout structure). The page cannot be prerendered statically. ```typescript import { cookies } from 'next/headers'; import { db } from '@/lib/db'; // ANTI-PATTERN: Top-level page awaits dynamic IO (cookies and uncached db call). // Under Next.js 15 Dynamic IO / PPR, this de-optimizes the entire page shell. export default async function Page() { const cookieStore = await cookies(); const sessionId = cookieStore.get('session_id')?.value; // Uncached dynamic database read at the root of the page const userCart = sessionId ? await db.cart.findUnique({ where: { sessionId } }) : null; return ( <main className="container mx-auto p-4"> <header className="hero-banner"> <h1>Welcome to Store</h1> <p>Explore our statically pre-rendered catalog below.</p> </header> <div className="cart-preview"> {userCart ? <span>Items: {userCart.items.length}</span> : <span>Cart empty</span>} </div> </main> ); } ``` #### Production Standard (Correct) > **Standard**: The top-level `Page` component is fully synchronous and static, allowing Next.js 15 PPR to prerender the static HTML shell at build time. The dynamic cookie check and database access are encapsulated in `<DynamicCart />` and wrapped in `<Suspense>`, streaming dynamic content at request time without de-optimizing the page shell. ```typescript import { Suspense } from 'react'; import { cookies } from 'next/headers'; import { db } from '@/lib/db'; import { CartSkeleton } from '@/components/cart-skeleton'; // Dynamic data read encapsulated in an isolated async Server Component async function DynamicCart() { const cookieStore = await cookies(); const sessionId = cookieStore.get('session_id')?.value; if (!sessionId) return <span>Cart empty</span>; const userCart = await db.cart.findUnique({ where: { sessionId } }); return <span>Items: {userCart?.items.length ?? 0}</span>; } // Top-level Page remains static; dynamic branch is streamed via Suspense export default function Page() { return ( <main className="container mx-auto p-4"> <header className="hero-banner"> <h1>Welcome to Store</h1> <p>Explore our statically pre-rendered catalog below.</p> </header> <div className="cart-preview"> <Suspense fallback={<CartSkeleton />}> <DynamicCart /> </Suspense> </div> </main> ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Mandatory Suspense Encapsulation for Next.js 15 Dynamic IO and PPR

Mandatory Suspense Encapsulation for Next.js 15 Dynamic IO and PPR defines an industrial-grade behavioral standard for frontend engineering. Enforces that any uncached runtime data access, dynamic APIs (headers, cookies, searchParams), or uncached database operations under Next.js 15 dynamicIO/Partial Prerendering (PPR) are encapsulated within dedicated, isolated React Suspense boundaries. Prevents runtime de-optimization cascades where an uncached operation at a page or root layout level bubbles up and forces an entire static shell into dynamic runtime execution. 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: Leaking Dynamic IO and Runtime APIs to Page-Level Shells De-optimizing Static Partial Prerendering 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	Leaking Dynamic IO and Runtime APIs to Page-Level Shells De-optimizing Static Partial Prerendering	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 uncached dynamic IO operations (such as `cookies()`, `headers()`, database queries, or uncached third-party SDK calls) into dedicated async Server Components wrapped within an explicit `<Suspense fallback={<Skeleton />}>` boundary.

Engineers MUST ALWAYS isolate uncached dynamic IO operations (such as `cookies()`, `headers()`, database queries, or uncached third-party SDK calls) into dedicated async Server Components wrapped within an explicit `<Suspense fallback={<Skeleton />}>` boundary.

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.