AgentRules.org
RulesStacksClientsAuditorPrunerSelf-HealRFCsBenchmarkCLICI/CDAuthorsSubmit
This specification is maintained by the AgentRules Working Group. Have enhancements or want to claim maintainership?Submit Specification →
frontendcritical PriorityID: nextjs-15-ppr-dynamic-hole-streaming-isolation

Next.js 15 Partial Prerendering (PPR) Dynamic Hole Streaming Isolation

Next.js 15 Partial Prerendering requires strict boundary separation between static prerendered shells and dynamic runtime execution. Invoking dynamic APIs (e.g., cookies(), headers(), searchParams, or uncached database reads) in a route component without wrapping it in an explicit React Suspense boundary invalidates the prerendered shell and forces full-route server-side rendering de-optimization.

Prohibited Anti-Pattern: Calling dynamic request-time APIs directly in root layouts or page components without Suspense containment, de-optimizing the static shell into full SSR.

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: Next.js 15 Partial Prerendering (PPR) Dynamic Hole Streaming Isolation - Next.js 15 Partial Prerendering requires strict boundary separation between static prerendered shells and dynamic runtime execution. Invoking dynamic APIs (e.g., cookies(), headers(), searchParams, or uncached database reads) in a route component without wrapping it in an explicit React Suspense boundary invalidates the prerendered shell and forces full-route server-side rendering de-optimization.
globs: app/**/*.{ts,tsx}, src/app/**/*.{ts,tsx}
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/nextjs-15-ppr-dynamic-hole-streaming-isolation"
---

# Next.js 15 Partial Prerendering (PPR) Dynamic Hole Streaming Isolation

> **Severity**: CRITICAL | **Category**: frontend
> **Anti-Pattern Warning**: Calling dynamic request-time APIs directly in root layouts or page components without Suspense containment, de-optimizing the static shell into full SSR.

## System Constraints
You are a Principal Architect enforcing Next.js 15 Partial Prerendering (PPR) invariants. You must prevent dynamic request-time leakage into deterministic static prerender shells. Any access to runtime dynamic APIs (cookies, headers, searchParams, uncached external IO) must be strictly isolated inside dedicated leaf components wrapped with explicit React Suspense boundaries with deterministic fallbacks.

## Strict Guidelines
- Engineers MUST ALWAYS isolate dynamic request-time operations (cookies, headers, dynamic searchParams, uncached fetches) inside dedicated child Server Components.
- Engineers MUST wrap every dynamic Server Component within an explicit <Suspense fallback={<Skeleton />}> boundary in the parent Page or Layout.
- Root page and layout components MUST NOT directly await dynamic functions (such as `cookies()` or `headers()`) at the top level when PPR is enabled.
- Components NEVER execute top-level uncached database or third-party service calls directly within static shell components.
- Fallback components in <Suspense> MUST be deterministic, lightweight, and completely free of dynamic API dependencies.
- Route segments utilizing PPR SHOULD explicitly export `export const experimental_ppr = true` to assert boundary verification at build time.

## Bad vs Good Implementations
### Isolating Dynamic Request Headers and Cookies into Suspended Leaf Components

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Calling `await cookies()` directly inside the top-level Page component de-opts Next.js from prerendering the static shell at build time, converting the entire page into a dynamic, blocking server-rendered response.
```typescript
import { cookies } from 'next/headers';
import { CartSummary } from '@/components/cart-summary';
import { ShellLayout } from '@/components/shell';

export const experimental_ppr = true;

// ANTI-PATTERN: Top-level dynamic API access forces entire page into runtime SSR
export default async function Page() {
  const cookieStore = await cookies();
  const token = cookieStore.get('session_token')?.value;
  
  return (
    <ShellLayout>
      <main className="p-6">
        <h1>Product Dashboard</h1>
        <CartSummary sessionToken={token} />
      </main>
    </ShellLayout>
  );
}
```

#### Production Standard (Correct)
> **Standard**: The dynamic `cookies()` invocation is isolated in `DynamicCartSummary` and wrapped with `<Suspense>`. The static `ShellLayout` and `<h1>` are prerendered and served instantly from edge cache, while the dynamic hole streams concurrently.
```typescript
import { Suspense } from 'react';
import { cookies } from 'next/headers';
import { CartSummarySkeleton } from '@/components/cart-summary-skeleton';
import { ShellLayout } from '@/components/shell';

export const experimental_ppr = true;

async function DynamicCartSummary() {
  const cookieStore = await cookies();
  const token = cookieStore.get('session_token')?.value;
  
  return <CartSummary sessionToken={token} />;
}

// INVARIANT: Static shell is preserved; dynamic hole is streamed via Suspense
export default function Page() {
  return (
    <ShellLayout>
      <main className="p-6">
        <h1>Product Dashboard</h1>
        <Suspense fallback={<CartSummarySkeleton />}>
          <DynamicCartSummary />
        </Suspense>
      </main>
    </ShellLayout>
  );
}
```
Recommended MCP Servers (mcp-serverlist.com)

Equip agent with system tools to verify code for this stack.

Next.js Build & Diagnostic MCP
Validates Next.js build manifests and catches dynamic de-optimization boundaries during static compilation.
Recommended Agent Skills (askills.dev)

Ready-to-use executable skill functions tailored to this stack.

Next.js Route Segment Analyzer CLI
Inspects static vs dynamic route indicators in Next.js build output to guarantee PPR static shell emission.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: Next.js 15 Partial Prerendering (PPR) Dynamic Hole Streaming Isolation

Next.js 15 Partial Prerendering (PPR) Dynamic Hole Streaming Isolation defines an industrial-grade behavioral standard for frontend engineering. Next.js 15 Partial Prerendering requires strict boundary separation between static prerendered shells and dynamic runtime execution. Invoking dynamic APIs (e.g., cookies(), headers(), searchParams, or uncached database reads) in a route component without wrapping it in an explicit React Suspense boundary invalidates the prerendered shell and forces full-route server-side rendering de-optimization. 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: Calling dynamic request-time APIs directly in root layouts or page components without Suspense containment, de-optimizing the static shell into full SSR. 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 ModeAI Symptom (The Anti-Pattern)SeverityProduction Impact & Remedy
AI Hallucination & Deprecation DriftCalling dynamic request-time APIs directly in root layouts or page components without Suspense containment, de-optimizing the static shell into full SSR.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 InconsistencyAI 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:

1

Engineers MUST ALWAYS isolate dynamic request-time operations (cookies, headers, dynamic searchParams, uncached fetches) inside dedicated child Server Components.

Engineers MUST ALWAYS isolate dynamic request-time operations (cookies, headers, dynamic searchParams, uncached fetches) inside dedicated child Server Components.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
2

Engineers MUST wrap every dynamic Server Component within an explicit <Suspense fallback={<Skeleton />}> boundary in the parent Page or Layout.

Engineers MUST wrap every dynamic Server Component within an explicit <Suspense fallback={<Skeleton />}> boundary in the parent Page or Layout.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
3

Root page and layout components MUST NOT directly await dynamic functions (such as `cookies()` or `headers()`) at the top level when PPR is enabled.

Root page and layout components MUST NOT directly await dynamic functions (such as `cookies()` or `headers()`) at the top level when PPR is enabled.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
4

Components NEVER execute top-level uncached database or third-party service calls directly within static shell components.

Components NEVER execute top-level uncached database or third-party service calls directly within static shell components.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
5

Fallback components in <Suspense> MUST be deterministic, lightweight, and completely free of dynamic API dependencies.

Fallback components in <Suspense> MUST be deterministic, lightweight, and completely free of dynamic API dependencies.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
6

Route segments utilizing PPR SHOULD explicitly export `export const experimental_ppr = true` to assert boundary verification at build time.

Route segments utilizing PPR SHOULD explicitly export `export const experimental_ppr = true` to assert boundary verification at build time.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
Technical Questions & Answers

Frequently Asked Technical Questions

Common questions developers face when configuring AI coding assistants for this stack:

Q:Why is Next.js 15 Partial Prerendering (PPR) Dynamic Hole Streaming Isolation critical for AI coding assistants?

Next.js 15 Partial Prerendering requires strict boundary separation between static prerendered shells and dynamic runtime execution. Invoking dynamic APIs (e.g., cookies(), headers(), searchParams, or uncached database reads) in a route component without wrapping it in an explicit React Suspense boundary invalidates the prerendered shell and forces full-route server-side rendering de-optimization. Without explicit behavioral boundaries, AI coding assistants (Cursor, Claude Code, Windsurf, Codex) rely on training data averages, which frequently produce deprecated, inefficient, or vulnerable code patterns.

Q:How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Calling dynamic request-time APIs directly in root layouts or page components without Suspense containment, de-optimizing the static shell into full SSR.) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q:Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q:Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

Open Specification · CC BY 4.0·Free for Personal, Team & Commercial In-Repo Use

Citation & Open Source Attribution Guidelines

This specification is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). You are completely free to adapt and share this rule in your workspace. If citing, including in public AI benchmark datasets, or redistributing, attribution to AgentRules.org is required.

Related FRONTEND Rules

View all rules →
frontend
119

SolidStart 1.0 Server Functions & Async Boundaries Production Standard

SolidStart 1.0 relies on the Vinxi bundler to split `server$` closures into independent HTTP POST RPC endpoints. Direct lexical closure over client signals within `server$` scopes or failure to demarcate async boundaries with `<Suspense>` causes silent serialization failures, client-bundle secret leaks, and SSR hydration mismatches. Enforcing strict parameter passing, runtime input validation, and Solid async primitives maintains security and fine-grained reactivity across network boundaries.

frontend
119

Astro 5 Actions & Content Layer Production Standard

Enforces strict type safety and architectural correctness for Astro 5 Server Actions and the zero-waterfall Content Layer API. Prevents runtime contract mismatches, hydration mismatches, and unhandled mutation exceptions across dynamic and prerendered boundaries. Failure to follow these patterns leads to silent data fetching waterfalls, build-time cache corruptions, and unhandled server action exceptions.

frontend
51

Nuxt 4 Nitro Server Engine & Shared Directory Production Standard

Nuxt 4 enforces strict boundary segregation between client UI in the app/ directory, backend endpoints in server/, and universal contracts in shared/. Violating cross-boundary isolation or maintaining module-scoped state in Nitro server handlers causes catastrophic cross-request data corruption and hydration mismatches under concurrent production traffic. Architects must enforce request-isolated H3 event contexts, universal serialization schemas, and strict path-alias boundaries.

1 Rule in Stack

Next.js