React Router 7 Framework Mode Hydration, Typegen & Single-Fetch Invariants

--- description: React Router 7 Framework Mode Hydration, Typegen & Single-Fetch Invariants - Enforces strict hydration boundaries, Single Fetch TurboStream serialization, and native Route Typegen contracts in React Router 7 framework mode. Prevents hydration mismatches, double-fetch cascades, broken promise streaming, and legacy Remix migration regressions. globs: app/**/+types/**/*.{ts,tsx}, app/routes/**/*.{ts,tsx}, app/root.tsx alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-router-7-hydration-typegen-single-fetch-guardrail" --- # React Router 7 Framework Mode Hydration, Typegen & Single-Fetch Invariants > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Bypassing Route Typegen, Misconfiguring clientLoader Hydration Flags, and Using Deprecated defer() in React Router 7 ## System Constraints You are a Principal Software Architect enforcing React Router 7 Framework Mode standards. You must mandate strict adherence to Route Module Typegen conventions, correct clientLoader hydration mechanics, Single Fetch streaming semantics (TurboStream), and the complete elimination of deprecated Remix v2 patterns. ## Strict Guidelines - Engineers MUST ALWAYS import route types exclusively from the route's relative typegen artifact (`import type { Route } from "./+types/[route-filename]"`) rather than manually constructing types with generic parameters. - Engineers MUST NOT import from deprecated `@remix-run/*` packages; all framework runtime primitives must be sourced from `react-router`. - Engineers MUST NOT use the deprecated `defer()` utility; React Router 7 Single Fetch natively streams bare Promises returned directly from `loader` functions via TurboStream. - Engineers MUST explicitly export `clientLoader.hydrate = true` if `clientLoader` is intended to execute during initial SSR hydration, and must otherwise rely on the server loader for initial document paint. - Engineers MUST ensure that any `clientLoader` utilizing `serverLoader()` handles the hydrated payload structure correctly without triggering double-fetch cascades. - Components NEVER await raw streamed Promises directly inside the root component body; they must be resolved concurrently within `<Suspense>` boundaries using `<Await>` or React's `use()` hook. - Services MUST ensure all loader return values conform to TurboStream serializable types (primitives, plain objects, Arrays, Maps, Sets, Dates, Errors, and Promises), rejecting raw class instances with private state or non-transferable prototype methods. ## Bad vs Good Implementations ### RR7 Streaming & Typegen Hydration Pattern #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Uses legacy @remix-run imports, deprecated defer() API, manual unsafe LoaderData casting bypassing RR7 typegen, and defines a clientLoader without specifying `clientLoader.hydrate = true`, causing silent hydration desynchronization and fallback stalls. ```typescript // @ts-nocheck - Anti-pattern: Deprecated Remix imports, manual LoaderFunctionArgs, legacy defer, missing typegen import { defer, type LoaderFunctionArgs } from "@remix-run/node"; import { useLoaderData, Await } from "@remix-run/react"; import { Suspense } from "react"; interface LoaderData { critical: string; streamed: Promise<{ metrics: number[] }>; } export async function loader({ request }: LoaderFunctionArgs) { const critical = "essential-header-data"; const streamed = fetchSlowMetrics(request); // BAD: defer is deprecated in React Router 7 Single Fetch return defer({ critical, streamed }); } // BAD: clientLoader without hydrate = true runs only on client navigation, // causing cache desynchronization if the author expected it to run on initial load. export async function clientLoader({ serverLoader }: any) { const data = await serverLoader(); return { ...data, clientTimestamp: Date.now() }; } export default function RouteComponent() { const data = useLoaderData() as LoaderData; // BAD: Unsound type assertion bypassing typegen return ( <div> <h1>{data.critical}</h1> <Suspense fallback={<div>Loading metrics...</div>}> <Await resolve={data.streamed}> {(metrics) => <div>{metrics.metrics.join(", ")}</div>} </Await> </Suspense> </div> ); } ``` #### Production Standard (Correct) > **Standard**: Implements native React Router 7 framework mode semantics: imports strictly typed Route interfaces from typegen (`./+types/dashboard`), passes raw promises directly for Single Fetch TurboStream serialization, correctly configures `clientLoader.hydrate = true`, and uses strictly typed `Route.ComponentProps`. ```typescript import { Suspense, use } from "react"; import { Await } from "react-router"; import type { Route } from "./+types/dashboard"; async function fetchSlowMetrics(signal: AbortSignal): Promise<{ metrics: number[] }> { const res = await fetch("https://api.internal/metrics", { signal }); if (!res.ok) throw new Error("Failed to fetch metrics"); return res.json(); } export async function loader({ request }: Route.LoaderArgs) { const critical = "essential-header-data"; // GOOD: Single Fetch natively supports raw Promises and TurboStream serialization const streamed = fetchSlowMetrics(request.signal); return { critical, streamed }; } export async function clientLoader({ serverLoader }: Route.ClientLoaderArgs) { const serverData = await serverLoader(); return { ...serverData, clientHydratedAt: Date.now(), }; } // GOOD: Explicitly opt-in if clientLoader must run on initial SSR hydration clientLoader.hydrate = true as const; export default function DashboardRoute({ loaderData }: Route.ComponentProps) { return ( <main> <h1>{loaderData.critical}</h1> <Suspense fallback={<p aria-busy="true">Streaming analytics...</p>}> <Await resolve={loaderData.streamed}> {(metrics) => <section>{metrics.metrics.join(", ")}</section>} </Await> </Suspense> </main> ); } ```

Architectural Specification & Invariant Rationale

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

React Router 7 Framework Mode Hydration, Typegen & Single-Fetch Invariants defines an industrial-grade behavioral standard for frontend engineering. Enforces strict hydration boundaries, Single Fetch TurboStream serialization, and native Route Typegen contracts in React Router 7 framework mode. Prevents hydration mismatches, double-fetch cascades, broken promise streaming, and legacy Remix migration regressions. 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: Bypassing Route Typegen, Misconfiguring clientLoader Hydration Flags, and Using Deprecated defer() 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	Bypassing Route Typegen, Misconfiguring clientLoader Hydration Flags, and Using Deprecated defer() 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 types exclusively from the route's relative typegen artifact (`import type { Route } from "./+types/[route-filename]"`) rather than manually constructing types with generic parameters.

Engineers MUST ALWAYS import route types exclusively from the route's relative typegen artifact (`import type { Route } from "./+types/[route-filename]"`) rather than manually constructing types with generic parameters.

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.