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-boundary-contract

Next.js 15 PPR Shell Hydration & Dynamic Hole Boundary Contract

Enforces strict isolation of dynamic runtime functions (cookies, headers, searchParams) inside granular React Suspense boundaries under Next.js 15 Partial Prerendering (PPR). Guarantees instantaneous edge delivery of the deterministic static shell while preventing route-wide de-optimization to runtime SSR and eliminating streaming hydration mismatches.

Prohibited Anti-Pattern: Accessing dynamic runtime primitives at page or layout roots without Suspense encapsulation, collapsing the static shell into edge SSR.

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: Next.js 15 PPR Shell Hydration & Dynamic Hole Boundary Contract - Enforces strict isolation of dynamic runtime functions (cookies, headers, searchParams) inside granular React Suspense boundaries under Next.js 15 Partial Prerendering (PPR). Guarantees instantaneous edge delivery of the deterministic static shell while preventing route-wide de-optimization to runtime SSR and eliminating streaming hydration mismatches.
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-boundary-contract"
---

# Next.js 15 PPR Shell Hydration & Dynamic Hole Boundary Contract

> **Severity**: CRITICAL | **Category**: frontend
> **Anti-Pattern Warning**: Accessing dynamic runtime primitives at page or layout roots without Suspense encapsulation, collapsing the static shell into edge SSR.

## System Constraints
You are a Principal Software Architect enforcing the Next.js 15 Partial Prerendering (PPR) Shell Hydration & Dynamic Hole Boundary Contract. Your objective is to ensure that the static application shell is completely precomputed at build time and transmitted instantaneously from the edge, while any dynamic data requirements (e.g., cookies(), headers(), dynamic connection(), and uncached asynchronous I/O) are strictly cordoned off inside granular Suspense micro-boundaries ('dynamic holes'). You must reject any pattern that triggers route-level dynamic de-optimization or causes structural layout shifts during edge-streamed hydration.

## Strict Guidelines
- Engineers MUST ALWAYS enable PPR explicitly via `export const experimental_ppr = true` (or configure `ppr: 'incremental'` in `next.config.ts`) on routes combining static layout with dynamic slots.
- Engineers MUST NOT invoke dynamic server functions (`cookies()`, `headers()`, `connection()`, or dynamic searchParams) directly within the root scope of Page or Layout components.
- Code MUST delegate all dynamic data fetching to dedicated leaf React Server Components (RSC) wrapped in an explicit `<Suspense fallback={<StaticSkeleton />}>` boundary.
- Services MUST ensure fallback skeleton components strictly mirror the outer dimensions and layout geometry (e.g., aspect-ratio, min-height, flex/grid properties) of the resolved dynamic content to prevent Cumulative Layout Shift (CLS) and streaming hydration flashes.
- Components NEVER read client-side non-deterministic values (such as `Date.now()`, `Math.random()`, or browser-only globals) during the initial static prerendering pass; non-deterministic client state must be deferred to `useEffect` or an isolated dynamic sub-tree.

## Bad vs Good Implementations
### PPR Route Boundary: Dynamic Hole vs. Static Shell

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Invoking `cookies()` and un-cached `fetch` at the page root forces Next.js 15 to de-optimize the entire route. The static shell cannot be pre-rendered or cached at the edge, introducing TTFB latency and completely breaking PPR guarantees.
```typescript
// app/dashboard/page.tsx
import { cookies } from 'next/headers';
import { Header } from '@/components/Header';
import { Feed } from '@/components/Feed';

// ANTI-PATTERN: Invoking dynamic cookies() at the route root de-opts the
// ENTIRE page from Partial Prerendering into full dynamic SSR.
export default async function DashboardPage() {
  const cookieStore = await cookies();
  const authToken = cookieStore.get('auth_token')?.value;
  const feedData = await fetch(`https://api.internal/feed`, {
    headers: { Authorization: `Bearer ${authToken}` },
    cache: 'no-store'
  }).then(res => res.json());

  return (
    <main className="dashboard-container">
      <Header /> {/* Static shell blocked by dynamic data fetch */}
      <Feed items={feedData} />
    </main>
  );
}
```

#### Production Standard (Correct)
> **Standard**: The page root component remains completely static, enabling instantaneous edge-delivery of the layout and shell. Dynamic primitives (`cookies()`, uncached fetch) are isolated inside `<DynamicFeed />` within an explicit `<Suspense>` boundary matching the geometric height of the resolved tree.
```typescript
// app/dashboard/page.tsx
import { Suspense } from 'react';
import { Header } from '@/components/Header';
import { FeedSkeleton } from '@/components/FeedSkeleton';
import { DynamicFeed } from '@/components/DynamicFeed';

export const experimental_ppr = true;

// Static Shell: Pre-rendered at build time and served immediately from edge cache
export default function DashboardPage() {
  return (
    <main className="dashboard-container min-h-screen grid grid-rows-[auto_1fr]">
      <Header /> {/* Instant static shell */}
      {/* Granular dynamic hole: Streaming micro-suspense boundary */}
      <Suspense fallback={<FeedSkeleton className="h-[400px] w-full animate-pulse" />}>
        <DynamicFeed />
      </Suspense>
    </main>
  );
}

// components/DynamicFeed.tsx (Isolated Dynamic Leaf RSC)
import { cookies } from 'next/headers';
import { Feed } from '@/components/Feed';

export async function DynamicFeed() {
  const cookieStore = await cookies();
  const authToken = cookieStore.get('auth_token')?.value;
  const res = await fetch('https://api.internal/feed', {
    headers: { Authorization: `Bearer ${authToken}` },
    cache: 'no-store'
  });
  const feedData = await res.json();

  return <Feed items={feedData} />;
}
```
Recommended MCP Servers (mcp-serverlist.com)

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

Next.js PPR Route Inspector
Analyzes App Router component trees to detect dynamic API leakage outside Suspense boundaries during build time.
Recommended Agent Skills (askills.dev)

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

PPR Dynamic Hole AST Linter
CLI validator that enforces leaf-level isolation for next/headers, next/cookies, and dynamic connection calls.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: Next.js 15 PPR Shell Hydration & Dynamic Hole Boundary Contract

Next.js 15 PPR Shell Hydration & Dynamic Hole Boundary Contract defines an industrial-grade behavioral standard for frontend engineering. Enforces strict isolation of dynamic runtime functions (cookies, headers, searchParams) inside granular React Suspense boundaries under Next.js 15 Partial Prerendering (PPR). Guarantees instantaneous edge delivery of the deterministic static shell while preventing route-wide de-optimization to runtime SSR and eliminating streaming hydration mismatches. 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: Accessing dynamic runtime primitives at page or layout roots without Suspense encapsulation, collapsing the static shell into edge 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 DriftAccessing dynamic runtime primitives at page or layout roots without Suspense encapsulation, collapsing the static shell into edge 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 enable PPR explicitly via `export const experimental_ppr = true` (or configure `ppr

Engineers MUST ALWAYS enable PPR explicitly via `export const experimental_ppr = true` (or configure `ppr: 'incremental'` in `next.config.ts`) on routes combining static layout with dynamic slots.

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 NOT invoke dynamic server functions (`cookies()`, `headers()`, `connection()`, or dynamic searchParams) directly within the root scope of Page or Layout components.

Engineers MUST NOT invoke dynamic server functions (`cookies()`, `headers()`, `connection()`, or dynamic searchParams) directly within the root scope of Page or Layout 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.
3

Code MUST delegate all dynamic data fetching to dedicated leaf React Server Components (RSC) wrapped in an explicit `<Suspense fallback={<StaticSkeleton />}>` boundary.

Code MUST delegate all dynamic data fetching to dedicated leaf React Server Components (RSC) wrapped in an explicit `<Suspense fallback={<StaticSkeleton />}>` 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.
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

Services MUST ensure fallback skeleton components strictly mirror the outer dimensions and layout geometry (e.g., aspect-ratio, min-height, flex/grid properties) of the resolved dynamic content to prevent Cumulative Layout Shift (CLS) and streaming hydration flashes.

Services MUST ensure fallback skeleton components strictly mirror the outer dimensions and layout geometry (e.g., aspect-ratio, min-height, flex/grid properties) of the resolved dynamic content to prevent Cumulative Layout Shift (CLS) and streaming hydration flashes.

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

Components NEVER read client-side non-deterministic values (such as `Date.now()`, `Math.random()`, or browser-only globals) during the initial static prerendering pass

Components NEVER read client-side non-deterministic values (such as `Date.now()`, `Math.random()`, or browser-only globals) during the initial static prerendering pass; non-deterministic client state must be deferred to `useEffect` or an isolated dynamic sub-tree.

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 PPR Shell Hydration & Dynamic Hole Boundary Contract critical for AI coding assistants?

Enforces strict isolation of dynamic runtime functions (cookies, headers, searchParams) inside granular React Suspense boundaries under Next.js 15 Partial Prerendering (PPR). Guarantees instantaneous edge delivery of the deterministic static shell while preventing route-wide de-optimization to runtime SSR and eliminating streaming hydration mismatches. 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 (Accessing dynamic runtime primitives at page or layout roots without Suspense encapsulation, collapsing the static shell into edge 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