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

--- description: React Router 7 Framework Mode: Hydration, Single-Fetch, and Typegen Invariants - Enforces strict adherence to React Router 7 framework mode data architecture, mandating typegen imports via './+types/', prohibiting legacy json() and defer() wrappers in single-fetch mode, and ensuring accurate clientLoader hydration synchronization to eliminate SSR hydration mismatches. globs: 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-guardrail" --- # React Router 7 Framework Mode: Hydration, Single-Fetch, and Typegen Invariants > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Using Legacy json()/defer() Wrappers and Manual useLoaderData Generics with Unsynchronized clientLoader Hydration ## System Constraints You are a Principal Software Architect enforcing React Router 7 Framework Mode standards. Mandate zero use of legacy Remix v2 data APIs (e.g., json(), defer()), enforce auto-generated Route module typegen ('./+types/{name}'), guarantee single-fetch turbo-stream compliance for naked promises and rich data types, and prevent hydration tearing between server loaders and clientLoaders. ## Strict Guidelines - Engineers MUST ALWAYS import route types directly from the collocated auto-generated typegen module: `import type { Route } from './+types/{file_basename}';`. - Engineers MUST NOT use legacy `json()` or `defer()` helpers; in React Router 7 Single Fetch mode, return raw JavaScript objects, promises, Dates, Sets, and Maps directly from `loader` and `action`. - Route components MUST consume `Route.ComponentProps` for type-safe props including `{ loaderData, actionData, params, matches }` instead of invoking manually typed hooks like `useLoaderData<typeof loader>()`. - Engineers MUST explicitly set `clientLoader.hydrate = true` if and only if the `clientLoader` must execute during the initial SSR document hydration pass to populate cache or bypass server data. - Components NEVER execute browser-specific global access (window, localStorage) directly within the render body or loader without guarding behind hydration completion or dedicated `clientLoader`/`useEffect` boundaries. ## Bad vs Good Implementations ### React Router 7 Route Module Data Hydration and Typegen #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Uses deprecated json() wrapper which disables native turbo-stream serialization in React Router 7 single-fetch mode, relies on generic type assertion instead of generated route types, and mishandles clientLoader without specifying the hydrate boolean property. ```typescript import { json } from '@remix-run/node'; import { useLoaderData, type LoaderFunctionArgs } from 'react-router'; import { Suspense } from 'react'; import { Await } from 'react-router'; // ANTI-PATTERN: Using deprecated json/defer, manual LoaderFunctionArgs, and manual generics export async function loader({ params }: LoaderFunctionArgs) { const user = await fetchUser(params.userId); const slowMetrics = fetchMetrics(params.userId); // Promise return json({ user, slowMetrics: slowMetrics.toString() }); // Breaks turbo-stream promise streaming } // ANTI-PATTERN: clientLoader defined without explicit hydrate property, risking mismatch export async function clientLoader({ serverLoader }: any) { return serverLoader(); } export default function UserProfile() { const { user } = useLoaderData<typeof loader>(); // ANTI-PATTERN: Manual inference misses typegen benefits return <div><h1>{user.name}</h1></div>; } async function fetchUser(id?: string) { return { name: 'Alice' }; } function fetchMetrics(id?: string) { return Promise.resolve(42); } ``` #### Production Standard (Correct) > **Standard**: Strictly adheres to React Router 7 framework mode typegen conventions (`Route.LoaderArgs`, `Route.ComponentProps`), returns raw naked promises and native Dates for single-fetch turbo-stream serialization, and explicitly marks `clientLoader.hydrate = true`. ```typescript import { Suspense } from 'react'; import { Await } from 'react-router'; import type { Route } from './+types/user-profile'; // INVARIANT: Use auto-generated Route.LoaderArgs; return naked objects & streaming promises export async function loader({ params }: Route.LoaderArgs) { const user = await fetchUser(params.userId); const slowMetrics = fetchMetrics(params.userId); // Streaming naked promise // RR7 single fetch serializes raw objects, Promises, Dates, Maps, Sets via turbo-stream return { user, slowMetrics, loadedAt: new Date(), }; } // INVARIANT: Explicitly declare clientLoader hydration behavior export async function clientLoader({ serverLoader }: Route.ClientLoaderArgs) { return await serverLoader(); } clientLoader.hydrate = true as const; // INVARIANT: Type route component using Route.ComponentProps directly export default function UserProfile({ loaderData }: Route.ComponentProps) { const { user, slowMetrics, loadedAt } = loaderData; return ( <main> <h1>{user.name}</h1> <p>Rendered at: {loadedAt.toISOString()}</p> <Suspense fallback={<span>Loading metrics...</span>}> <Await resolve={slowMetrics}> {(metrics) => <div>Metrics Score: {metrics}</div>} </Await> </Suspense> </main> ); } async function fetchUser(id: string) { return { name: 'Alice' }; } function fetchMetrics(id: string): Promise<number> { return Promise.resolve(42); } ```

Architectural Specification & Invariant Rationale

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

React Router 7 Framework Mode: Hydration, Single-Fetch, and Typegen Invariants defines an industrial-grade behavioral standard for frontend engineering. Enforces strict adherence to React Router 7 framework mode data architecture, mandating typegen imports via './+types/', prohibiting legacy json() and defer() wrappers in single-fetch mode, and ensuring accurate clientLoader hydration synchronization to eliminate SSR hydration mismatches. 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: Using Legacy json()/defer() Wrappers and Manual useLoaderData Generics with Unsynchronized clientLoader Hydration 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	Using Legacy json()/defer() Wrappers and Manual useLoaderData Generics with Unsynchronized clientLoader Hydration	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 directly from the collocated auto-generated typegen module

Engineers MUST ALWAYS import route types directly from the collocated auto-generated typegen module: `import type { Route } from './+types/{file_basename}';`.

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.