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

--- description: React Router 7 Framework Mode Hydration, Typegen, and Single-Fetch Invariants - Enforces strict data boundaries, Single Fetch serialization, and typegen alignment in React Router 7 framework mode. Prevents hydration mismatches, double-fetching cascades, and clientLoader desynchronization when streaming deferred promises across SSR and client navigations. globs: app/**/*.{ts,tsx}, src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-router-v7-framework-hydration-boundaries" --- # React Router 7 Framework Mode Hydration, Typegen, and Single-Fetch Invariants > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Bypassing Typegen Route Module Types and Misconfiguring clientLoader.hydrate with Defer Streams ## System Constraints You are a Principal Software Architect enforcing React Router 7 (Remix) Framework Mode hydration, typegen contracts, and Single Fetch architectural invariants. You strictly disallow manual loader return type typing, unhandled stream rejections during SSR, omitting clientLoader.hydrate when clientLoader reads server state, and breaking TurboStream serialization boundaries. ## Strict Guidelines - Engineers MUST ALWAYS import and bind Route module types exclusively from the auto-generated './+types/{fileName}' module (e.g., `Route.LoaderArgs`, `Route.ComponentProps`). - Engineers MUST NOT manually define or cast loader return types via generics or `json<T>()`, as React Router 7 Single Fetch relies on compile-time typegen inference with native TurboStream serialization. - Engineers MUST explicitly set `clientLoader.hydrate = true` on any route defining a `clientLoader` if that `clientLoader` needs to run during initial SSR document hydration; otherwise, initial SSR loader data is skipped and replaced by client fetch cycles. - Engineers MUST ALWAYS wrap non-critical deferred promises returned from `loader` inside a `<Suspense>` boundary paired with `<Await>` on the component layer to prevent server-side blocking and hydration desync. - Components NEVER read non-serializable objects (such as class instances with non-enumerable methods or raw DOM references) through loader payloads, relying strictly on JSON-compatible types, Promises, Error instances, and standard JavaScript primitives supported by TurboStream. ## Bad vs Good Implementations ### Route Module Typegen and Hydration-Safe clientLoader Streaming #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Manually typing loader arguments and using type assertions bypasses RR7 typegen. Omitting `clientLoader.hydrate = true` causes RR7 to ignore the server payload on initial page load, forcing a redundant client fetch. Consuming an unresolved promise directly in the render tree without `<Suspense>` and `<Await>` triggers immediate hydration errors. ```typescript import { useLoaderData } from 'react-router'; import type { LoaderFunctionArgs } from 'react-router'; interface UserData { user: { id: string; name: string }; heavyMetrics: Promise<{ score: number }>; } // ANTI-PATTERN: Manual loader typing, legacy json() wrapper, and unconfigured clientLoader export async function loader({ params }: LoaderFunctionArgs) { return { user: await fetchUser(params.id), heavyMetrics: fetchMetrics(params.id) }; } export async function clientLoader({ serverLoader }: { serverLoader: () => Promise<any> }) { const serverData = await serverLoader(); return { ...serverData, cachedAt: Date.now() }; } // BUG: Missing clientLoader.hydrate = true causes initial SSR render to drop serverData export default function RouteComponent() { const data = useLoaderData() as UserData; return ( <div> <h1>{data.user.name}</h1> {/* BUG: Awaiting deferred stream directly without Suspense/Await causes hydration mismatch */} <div>Score: {(data.heavyMetrics as any).score}</div> </div> ); } async function fetchUser(id?: string) { return { id: id ?? '1', name: 'Dev' }; } async function fetchMetrics(id?: string) { return { score: 100 }; } ``` #### Production Standard (Correct) > **Standard**: Adopts canonical `./+types/profile` generated types. Uses native return objects compatible with RR7 Single Fetch. Declares `clientLoader.hydrate = true` to preserve server-rendered markup and prevent hydration waterfalls. Uses `<Suspense>` and `<Await>` to handle streamed promises cleanly without DOM synchronization failures. ```typescript import { Suspense } from 'react'; import { Await } from 'react-router'; import type { Route } from './+types/profile'; // INVARIANT: Native object return leverages Single Fetch TurboStream serialization export async function loader({ params }: Route.LoaderArgs) { return { user: await fetchUser(params.id), heavyMetrics: fetchMetrics(params.id) // Streamed deferred promise }; } // INVARIANT: Explicit hydrate flag ensures clientLoader runs during initial document load export async function clientLoader({ serverLoader }: Route.ClientLoaderArgs) { const serverData = await serverLoader(); return { ...serverData, cachedAt: Date.now() }; } clientLoader.hydrate = true as const; // INVARIANT: Route.ComponentProps gives full end-to-end type safety inferred from loader export default function RouteComponent({ loaderData }: Route.ComponentProps) { return ( <div> <h1>{loaderData.user.name}</h1> <Suspense fallback={<div>Loading telemetry metrics...</div>}> <Await resolve={loaderData.heavyMetrics}> {(metrics) => <div>Score: {metrics.score}</div>} </Await> </Suspense> </div> ); } async function fetchUser(id?: string) { return { id: id ?? '1', name: 'Dev' }; } async function fetchMetrics(id?: string) { return { score: 100 }; } ```

Architectural Specification & Invariant Rationale

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

React Router 7 Framework Mode Hydration, Typegen, and Single-Fetch Invariants defines an industrial-grade behavioral standard for frontend engineering. Enforces strict data boundaries, Single Fetch serialization, and typegen alignment in React Router 7 framework mode. Prevents hydration mismatches, double-fetching cascades, and clientLoader desynchronization when streaming deferred promises across SSR and client navigations. 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 Typegen Route Module Types and Misconfiguring clientLoader.hydrate with Defer Streams 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 Typegen Route Module Types and Misconfiguring clientLoader.hydrate with Defer Streams	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 and bind Route module types exclusively from the auto-generated './+types/{fileName}' module (e.g., `Route.LoaderArgs`, `Route.ComponentProps`).

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.