React Router 7 Framework Mode: Hydration, Single-Fetch, and Route Typegen Invariants

--- description: React Router 7 Framework Mode: Hydration, Single-Fetch, and Route Typegen Invariants - Enforces strict React Router 7 framework mode invariants across route module typegen, Single Fetch serialization boundaries, and clientLoader hydration lifecycles. Prevents hydration mismatches, broken turbo-stream serialization, and redundant network roundtrips caused by legacy Remix v2 primitives. globs: app/routes/**/*.{ts,tsx}, app/root.tsx, react-router.config.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/rr7-hydration-single-fetch-streaming-standard" --- # React Router 7 Framework Mode: Hydration, Single-Fetch, and Route Typegen Invariants > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Hydration mismatches, waterfall stalls, and broken serialization caused by legacy json/defer primitives and untyped clientLoader boundaries in React Router 7. ## System Constraints You are a Principal Software Architect enforcing React Router 7 (RR7) Framework Mode standards. Mandate strict conformance to Single Fetch data semantics, route module typegen via './+types/[route-name]', and deterministic clientLoader hydration configurations. Reject all legacy Remix primitives (`json`, `defer`) and untyped route hooks. ## Strict Guidelines - Engineers MUST ALWAYS import route contract types (`Route.LoaderArgs`, `Route.ActionArgs`, `Route.ComponentProps`) from the auto-generated `./+types/<route-filename>` module. - Engineers MUST NOT use deprecated `json()` or `defer()` helpers; React Router 7 Single Fetch natively serializes raw objects, Promises, Dates, BigInts, Errors, Sets, and Maps via turbo-stream. - Engineers MUST return unresolved Promises directly at the top level of the loader return object to initiate background streaming over Single Fetch. - Engineers MUST explicitly declare `clientLoader.hydrate = true` only when the clientLoader must execute during initial SSR hydration (e.g., reading client-side caches or IndexedDB). - Engineers MUST call `await serverLoader()` inside `clientLoader` when augmenting server data to prevent accidental bypass of SSR-rendered state. - Components NEVER use `useLoaderData<typeof loader>()` generic instantiation; route components MUST accept `{ loaderData }` typed by `Route.ComponentProps`. - Engineers MUST wrap all streamed loader promises inside `<Suspense fallback={...}>` and `<Await resolve={...}>` to prevent SSR render stalls. ## Bad vs Good Implementations ### Route Module Typegen and Streaming Single-Fetch Boundary #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Uses deprecated `defer()` from legacy Remix packages, bypasses RR7's `./+types` route typegen module, lacks `clientLoader.hydrate` explicit configuration (causing unexpected hydration behavior or redundant roundtrips), and falls back to manual generics on `useLoaderData`. ```typescript import { defer } from "@remix-run/node"; // DEPRECATED: Remix v2 legacy primitive import { useLoaderData, Await } from "@remix-run/react"; import { Suspense } from "react"; // ANTI-PATTERN: Untyped args, using defer(), and missing typegen route contract export async function loader({ request }: any) { const criticalData = await fetchCriticalUser(); const deferredStream = fetchAnalyticsStream(); return defer({ criticalData, deferredStream }); } // ANTI-PATTERN: clientLoader defined without .hydrate specifier // runs on client navigation but causes hydration flash if server HTML relied on loader export async function clientLoader({ request, serverLoader }: any) { return serverLoader(); } export default function Dashboard() { // ANTI-PATTERN: Manual loader typing prone to drift const { criticalData, deferredStream } = useLoaderData<typeof loader>(); return ( <div> <h1>{criticalData.name}</h1> <Suspense fallback={<p>Loading stream...</p>}> <Await resolve={deferredStream}>{(data: any) => <div>{data.metric}</div>}</Await> </Suspense> </div> ); } ``` #### Production Standard (Correct) > **Standard**: Adheres strictly to RR7 framework mode: leverages `./+types/dashboard` for static compile-time safety across loader and component, eliminates legacy `defer()`, uses Single Fetch naked promises for streaming, and declares `clientLoader.hydrate = true` deterministically. ```typescript import { Suspense } from "react"; import { Await } from "react-router"; import type { Route } from "./+types/dashboard"; // INVARIANT: Native Single-Fetch loader streaming via naked Promise and Route typegen export async function loader({ request }: Route.LoaderArgs) { const criticalData = await fetchCriticalUser(); const deferredStream = fetchAnalyticsStream(); // Unresolved Promise return { criticalData, deferredStream, }; } // INVARIANT: Explicit hydrate configuration prevents redundant client execution during SSR hydration export async function clientLoader({ serverLoader }: Route.ClientLoaderArgs) { const serverData = await serverLoader(); const localPreferences = localStorage.getItem("pref"); return { ...serverData, localPreferences, }; } clientLoader.hydrate = true as const; // INVARIANT: Route component props automatically typed by RR7 typegen export default function Dashboard({ loaderData }: Route.ComponentProps) { return ( <main> <h1>{loaderData.criticalData.name}</h1> <Suspense fallback={<p>Streaming telemetry...</p>}> <Await resolve={loaderData.deferredStream}> {(stream) => <div>Metric: {stream.metric}</div>} </Await> </Suspense> </main> ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React Router 7 Framework Mode: Hydration, Single-Fetch, and Route Typegen Invariants

React Router 7 Framework Mode: Hydration, Single-Fetch, and Route Typegen Invariants defines an industrial-grade behavioral standard for frontend engineering. Enforces strict React Router 7 framework mode invariants across route module typegen, Single Fetch serialization boundaries, and clientLoader hydration lifecycles. Prevents hydration mismatches, broken turbo-stream serialization, and redundant network roundtrips caused by legacy Remix v2 primitives. 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: Hydration mismatches, waterfall stalls, and broken serialization caused by legacy json/defer primitives and untyped clientLoader boundaries in React Router 7. 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	Hydration mismatches, waterfall stalls, and broken serialization caused by legacy json/defer primitives and untyped clientLoader boundaries in React Router 7.	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 import route contract types (`Route.LoaderArgs`, `Route.ActionArgs`, `Route.ComponentProps`) from the auto-generated `./+types/<route-filename>` module.

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.