React Router 7 Framework Mode Hydration & Single-Fetch Boundaries

--- description: React Router 7 Framework Mode Hydration & Single-Fetch Boundaries - Enforces single-fetch serialization boundaries, deterministic SSR hydration, and auto-generated route module typings in React Router 7 Framework Mode. Prohibits legacy Remix response primitives (`json()`, `defer()`) and ensures un-awaited streaming promises and `clientLoader.hydrate` flags maintain type safety and avoid hydration waterfalls. globs: app/**/+*.{ts,tsx}, app/routes/**/*.{ts,tsx}, src/routes/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/rr7-framework-mode-hydration-single-fetch" --- # React Router 7 Framework Mode Hydration & Single-Fetch Boundaries > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Legacy Response Serialization, Unchecked clientLoader Overrides, and Manual Route Prop Typing ## System Constraints You are a Principal Software Architect enforcing React Router 7 Framework Mode standards. Mandate zero usage of legacy Remix `json()` or `defer()` primitives, enforce strict consumption of auto-generated `./+types/<route>` contracts, and ensure single-fetch streaming hydration invariants are maintained without client-side waterfalls. ## Strict Guidelines - Engineers MUST NOT use legacy `json()` or `defer()` utilities from `@remix-run/node` or `react-router`; React Router 7 Single Fetch uses `turbo-stream` and accepts direct bare objects, native Promises, Sets, Maps, and Dates. - Engineers MUST ALWAYS type route components, loaders, and actions using auto-generated `Route` namespace imports from `./+types/[route-filename]` rather than manual type declarations. - Engineers MUST explicitly set `clientLoader.hydrate = true` ONLY when `clientLoader` is required to execute on the initial client-side hydration pass; omitting it leaves initial SSR data untouched until subsequent in-app navigations. - Components MUST wrap non-awaited streaming loader promises inside React `<Suspense>` boundaries coupled with the `<Await>` component to prevent blocking SSR critical path rendering. - Engineers MUST use `serverLoader()` within `clientLoader` when implementing optimistic caching layers to avoid duplicating network requests already executed on the server. - Loaders MUST NOT serialize non-cloneable objects (DOM nodes, closures, class instances with private state, Symbols) across the SSR wire. ## Bad vs Good Implementations ### React Router 7 Single Fetch Streaming and Typegen Invariants #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using legacy Remix `defer()` and `json()` wrappers bypasses the native turbo-stream single-fetch serializer, breaks type inference, and causes hydration mismatches when promises are rendered directly without `<Suspense>` and `<Await>`. ```typescript import { defer, json } from "@remix-run/node"; import { useLoaderData } from "@remix-run/react"; // ANTI-PATTERN: Using deprecated json/defer, manual typing, and broken hydration boundaries export async function loader() { const criticalData = await fetchCritical(); const slowData = fetchSlow(); // unawaited promise // BUG: defer() is obsolete in RR7 Single Fetch; causes turbo-stream serialization issues return defer({ critical: criticalData, deferred: slowData, }); } // ANTI-PATTERN: Manual prop typing instead of auto-generated route types export default function DashboardRoute() { const data = useLoaderData() as { critical: string; deferred: Promise<string> }; return ( <div> <h1>{data.critical}</h1> {/* BUG: Direct render of un-awaited promise without Suspense/Await causes hydration crash */} <p>{data.deferred as any}</p> </div> ); } ``` #### Production Standard (Correct) > **Standard**: Adheres to React Router 7 single-fetch contracts by returning raw typed objects with streaming promises, typing components and loaders using the auto-generated `./+types/dashboard` Route namespace, configuring `clientLoader.hydrate = false` to preserve server hydration state, and safely unwrapping promises with `<Suspense>` and `<Await>`. ```typescript import { Suspense } from "react"; import { Await } from "react-router"; import type { Route } from "./+types/dashboard"; import { fetchCritical, fetchSlow } from "~/api/metrics.server"; // PRODUCTION INVARIANT: Direct object return using RR7 Single Fetch, fully typed via Route namespace export async function loader({ request }: Route.LoaderArgs) { const critical = await fetchCritical(request); const streamed = fetchSlow(request); // Native Promise streaming return { critical, streamed }; } // Optional clientLoader cache: MUST declare serverLoader or specify hydrate boolean explicitly export async function clientLoader({ serverLoader }: Route.ClientLoaderArgs) { const serverData = await serverLoader(); return serverData; } clientLoader.hydrate = false; // Prevents redundant initial execution during SSR hydration export default function DashboardRoute({ loaderData }: Route.ComponentProps) { return ( <main> <h1>{loaderData.critical.title}</h1> <Suspense fallback={<div>Loading deferred metrics...</div>}> <Await resolve={loaderData.streamed}> {(resolved) => <div>Metric: {resolved.value}</div>} </Await> </Suspense> </main> ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React Router 7 Framework Mode Hydration & Single-Fetch Boundaries

React Router 7 Framework Mode Hydration & Single-Fetch Boundaries defines an industrial-grade behavioral standard for frontend engineering. Enforces single-fetch serialization boundaries, deterministic SSR hydration, and auto-generated route module typings in React Router 7 Framework Mode. Prohibits legacy Remix response primitives (`json()`, `defer()`) and ensures un-awaited streaming promises and `clientLoader.hydrate` flags maintain type safety and avoid hydration waterfalls. 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: Legacy Response Serialization, Unchecked clientLoader Overrides, and Manual Route Prop Typing 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	Legacy Response Serialization, Unchecked clientLoader Overrides, and Manual Route Prop Typing	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 NOT use legacy `json()` or `defer()` utilities from `@remix-run/node` or `react-router`

Engineers MUST NOT use legacy `json()` or `defer()` utilities from `@remix-run/node` or `react-router`; React Router 7 Single Fetch uses `turbo-stream` and accepts direct bare objects, native Promises, Sets, Maps, and Dates.

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.