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: next15-ppr-dynamic-io-boundary-invariant

Next.js 15 Partial Prerendering (PPR) and Dynamic-IO Boundary Isolation

Enforces strict isolation between static prerendered shell hierarchies and asynchronous dynamic I/O micro-tasks in Next.js 15. Prevents dynamic data APIs (cookies, headers, searchParams, uncached queries) from de-optimizing parent route shells into runtime SSR waterfalls. Mandates explicit React Suspense boundaries around all dynamic leaf nodes with synchronous, deterministic fallback skeletons.

Prohibited Anti-Pattern: Unwrapped Dynamic API Invocation at Route Root De-optimizing Static Shells into Blocking SSR

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: Next.js 15 Partial Prerendering (PPR) and Dynamic-IO Boundary Isolation - Enforces strict isolation between static prerendered shell hierarchies and asynchronous dynamic I/O micro-tasks in Next.js 15. Prevents dynamic data APIs (cookies, headers, searchParams, uncached queries) from de-optimizing parent route shells into runtime SSR waterfalls. Mandates explicit React Suspense boundaries around all dynamic leaf nodes with synchronous, deterministic fallback skeletons.
globs: app/**/*.{ts,tsx}, src/app/**/*.{ts,tsx}
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/next15-ppr-dynamic-io-boundary-invariant"
---

# Next.js 15 Partial Prerendering (PPR) and Dynamic-IO Boundary Isolation

> **Severity**: CRITICAL | **Category**: frontend
> **Anti-Pattern Warning**: Unwrapped Dynamic API Invocation at Route Root De-optimizing Static Shells into Blocking SSR

## System Constraints
You are a Principal Software Architect enforcing Next.js 15 Partial Prerendering (PPR) and Dynamic-IO boundary invariants. When evaluating or generating App Router code, mandate absolute structural separation between static prerendered HTML frames and dynamic runtime branches. Never allow dynamic operations (such as headers(), cookies(), uncached fetches, or unwrapped searchParams access) to execute in the synchronous path of Page or Layout component roots without an enclosing React Suspense boundary. Force streaming I/O to leaf micro-components and verify fallback skeletons emit zero dynamic calls.

## Strict Guidelines
- Engineers MUST ALWAYS isolate asynchronous dynamic operations (cookies(), headers(), searchParams, database calls) into distinct sub-components wrapped in <Suspense> with a deterministic, fully static fallback skeleton.
- Engineers MUST NOT invoke dynamic APIs (such as await cookies() or uncached fetch) directly inside RootLayout, nested layouts, or root Page component functions when experimental.ppr or dynamicIO is enabled.
- Components designated as Suspense fallbacks MUST remain 100% pure and deterministic, containing zero network fetches, dynamic imports, or server-time calculations to avoid hydration mismatches.
- Engineers MUST utilize the 'use cache' directive alongside revalidateTag or cacheTag for semi-static data, explicitly keeping it separate from real-time per-request dynamic streams.
- Code SHOULD call Next.js 15 connection() explicitly inside dynamic micro-components to signal intentional dynamic prerender execution boundaries to the compiler.
- Services MUST parallelize multiple dynamic data dependencies using Promise.all or decoupled child Suspense boundaries to eliminate sequential micro-task waterfalls.

## Bad vs Good Implementations
### Root Page Dynamic De-optimization vs. Suspense-Enclosed PPR Boundary

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Awaiting cookies() and performing an uncached fetch directly in DashboardPage forces Next.js to de-optimize the entire page, including StaticHero. The static shell cannot be served from the edge cache, creating a blocking server-side waterfall.
```typescript
import { cookies } from 'next/headers';
import { UserProfile } from '@/components/user-profile';
import { StaticHero } from '@/components/static-hero';

export const experimental_ppr = true;

// ANTI-PATTERN: Awaiting cookies() directly in the page body converts
// the entire route shell into dynamic SSR, destroying the static prerender benefit.
export default async function DashboardPage() {
  const cookieStore = await cookies();
  const token = cookieStore.get('auth_token')?.value;
  
  const res = await fetch(`https://api.internal/user`, {
    headers: { Authorization: `Bearer ${token}` },
    cache: 'no-store'
  });
  const user = await res.json();

  return (
    <main className="dashboard-container">
      <StaticHero />
      <UserProfile user={user} />
    </main>
  );
}
```

#### Production Standard (Correct)
> **Standard**: DashboardPage remains fully synchronous and static. The static HTML shell and StaticHero are prerendered and immediately served at edge speed, while DynamicUserProfile executes as an asynchronous streaming micro-task within an isolated Suspense boundary.
```typescript
import { Suspense } from 'react';
import { cookies } from 'next/headers';
import { connection } from 'next/server';
import { StaticHero } from '@/components/static-hero';
import { ProfileSkeleton } from '@/components/profile-skeleton';

export const experimental_ppr = true;

async function DynamicUserProfile() {
  // Explicitly mark execution boundary for Next.js 15 dynamicIO compiler
  await connection();
  const cookieStore = await cookies();
  const token = cookieStore.get('auth_token')?.value;
  
  const res = await fetch(`https://api.internal/user`, {
    headers: { Authorization: `Bearer ${token}` },
    cache: 'no-store'
  });
  const user = await res.json();

  return <div className="profile-card">{user.name}</div>;
}

// PRODUCTION INVARIANT: The page component remains static and immediately serves the shell,
// while the dynamic data micro-task streams independently inside Suspense.
export default function DashboardPage() {
  return (
    <main className="dashboard-container">
      <StaticHero />
      <Suspense fallback={<ProfileSkeleton />}>
        <DynamicUserProfile />
      </Suspense>
    </main>
  );
}
```
Recommended MCP Servers (mcp-serverlist.com)

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

Next.js Core Diagnostics MCP
Inspects compilation graphs, App Router dynamic boundaries, and Partial Prerendering build outputs for de-optimization leaks.
Recommended Agent Skills (askills.dev)

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

Next.js Bundle and Prerender Inspector
Analyzes Next.js build output to verify route dynamic/static classification markers (ƒ dynamic vs ○ static).
Architectural Specification & Invariant Rationale

Architectural Invariant Design: Next.js 15 Partial Prerendering (PPR) and Dynamic-IO Boundary Isolation

Next.js 15 Partial Prerendering (PPR) and Dynamic-IO Boundary Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforces strict isolation between static prerendered shell hierarchies and asynchronous dynamic I/O micro-tasks in Next.js 15. Prevents dynamic data APIs (cookies, headers, searchParams, uncached queries) from de-optimizing parent route shells into runtime SSR waterfalls. Mandates explicit React Suspense boundaries around all dynamic leaf nodes with synchronous, deterministic fallback skeletons. 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: Unwrapped Dynamic API Invocation at Route Root De-optimizing Static Shells into Blocking 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 DriftUnwrapped Dynamic API Invocation at Route Root De-optimizing Static Shells into Blocking SSRCritical
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 asynchronous dynamic operations (cookies(), headers(), searchParams, database calls) into distinct sub-components wrapped in <Suspense> with a deterministic, fully static fallback skeleton.

Engineers MUST ALWAYS isolate asynchronous dynamic operations (cookies(), headers(), searchParams, database calls) into distinct sub-components wrapped in <Suspense> with a deterministic, fully static fallback skeleton.

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 APIs (such as await cookies() or uncached fetch) directly inside RootLayout, nested layouts, or root Page component functions when experimental.ppr or dynamicIO is enabled.

Engineers MUST NOT invoke dynamic APIs (such as await cookies() or uncached fetch) directly inside RootLayout, nested layouts, or root Page component functions when experimental.ppr or dynamicIO 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.
3

Components designated as Suspense fallbacks MUST remain 100% pure and deterministic, containing zero network fetches, dynamic imports, or server-time calculations to avoid hydration mismatches.

Components designated as Suspense fallbacks MUST remain 100% pure and deterministic, containing zero network fetches, dynamic imports, or server-time calculations to avoid hydration mismatches.

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

Engineers MUST utilize the 'use cache' directive alongside revalidateTag or cacheTag for semi-static data, explicitly keeping it separate from real-time per-request dynamic streams.

Engineers MUST utilize the 'use cache' directive alongside revalidateTag or cacheTag for semi-static data, explicitly keeping it separate from real-time per-request dynamic streams.

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

Code SHOULD call Next.js 15 connection() explicitly inside dynamic micro-components to signal intentional dynamic prerender execution boundaries to the compiler.

Code SHOULD call Next.js 15 connection() explicitly inside dynamic micro-components to signal intentional dynamic prerender execution boundaries to the compiler.

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

Services MUST parallelize multiple dynamic data dependencies using Promise.all or decoupled child Suspense boundaries to eliminate sequential micro-task waterfalls.

Services MUST parallelize multiple dynamic data dependencies using Promise.all or decoupled child Suspense boundaries to eliminate sequential micro-task waterfalls.

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) and Dynamic-IO Boundary Isolation critical for AI coding assistants?

Enforces strict isolation between static prerendered shell hierarchies and asynchronous dynamic I/O micro-tasks in Next.js 15. Prevents dynamic data APIs (cookies, headers, searchParams, uncached queries) from de-optimizing parent route shells into runtime SSR waterfalls. Mandates explicit React Suspense boundaries around all dynamic leaf nodes with synchronous, deterministic fallback skeletons. 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 (Unwrapped Dynamic API Invocation at Route Root De-optimizing Static Shells into Blocking 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