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 architectural boundaries for React Router 7 Framework Mode applications using Single Fetch. Mandates the use of generated route module types (+types), prevents hydration mismatches across server-to-client loader transitions, and guarantees correct streaming deferred data consumption via turbo-stream serialization. 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-standard" --- # React Router 7 Framework Mode Hydration, Typegen, and Single-Fetch Invariants > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Bypassing Route Typegen, Misconfiguring clientLoader.hydrate, and Returning Legacy JSON Responses in Single Fetch ## System Constraints You are a Principal Engineer enforcing Remix React Router 7 Framework Mode Hydration. Mandate strict adherence to React Router 7's Single Fetch architecture, generated route module types (+types), turbo-stream deferred streaming patterns, and clientLoader hydration invariants. ## Strict Guidelines - Engineers MUST ALWAYS import Route types from the typegen module `./+types/<route-filename>` (e.g., `import type { Route } from './+types/dashboard'`) for `Route.ComponentProps`, `Route.LoaderArgs`, `Route.ActionArgs`, and `Route.ClientLoaderArgs`. - Engineers MUST NOT use deprecated Remix v2 patterns such as `json()` or `defer()` helpers; Single Fetch natively handles raw JS objects, Promises, Dates, Sets, Maps, and Errors through turbo-stream. - Engineers MUST explicitly set `clientLoader.hydrate = true` when `clientLoader` is required to run during initial page load; otherwise, `clientLoader` runs ONLY on client-side navigations while the server loader hydrates the initial render. - Code SHOULD wrap non-blocking loader promises with `<Suspense>` and `<Await>` components at the route component boundary to prevent blocking SSR Time-To-First-Byte. - Services MUST ensure that all non-streamed data returned from `loader` is fully resolved before returning, while deferred data is explicitly passed as unresolved promises within the returned object. - Components NEVER use `useLoaderData<typeof loader>()` in React Router 7 Framework Mode; always destructure `loaderData` directly from `Route.ComponentProps`. ## Bad vs Good Implementations ### React Router 7 Route Module: Single Fetch, Streaming, and Typegen Guardrail #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using deprecated `json()` wrappers disrupts Single Fetch serialization via turbo-stream, leading to hydration failures with Promises, Dates, and Maps. Manual typing via `as DashboardData` circumvents React Router 7 typegen, while omitting `clientLoader.hydrate = true` causes client/server boundary discrepancies during initial document hydration. ```typescript // app/routes/dashboard.tsx import { json } from "@remix-run/node"; // DEPRECATED in RR7 Single Fetch import { useLoaderData } from "@remix-run/react"; interface DashboardData { user: { name: string }; metrics: Promise<number[]>; } // Bad: Using legacy json/defer, manual interface, and ignoring clientLoader hydration rules export async function loader() { return json({ user: { name: "Alex" }, metrics: fetchMetrics(), // Deferred promise inside json() causes serialization failure }); } export async function clientLoader({ serverLoader }: any) { // Bad: clientLoader without clientLoader.hydrate = true will not run on initial SSR, // causing state drift or mismatch if the consumer assumes client cache pre-population. return serverLoader(); } export default function Dashboard() { // Bad: Unsafe loader casting instead of typegen ComponentProps const data = useLoaderData() as DashboardData; return <div>{data.user.name}</div>; } ``` #### Production Standard (Correct) > **Standard**: Uses React Router 7 `./+types/dashboard` typegen, ensuring type safety for `Route.LoaderArgs`, `Route.ClientLoaderArgs`, and `Route.ComponentProps`. Single Fetch returns raw objects with turbo-stream handling promise resolution seamlessly, while `clientLoader.hydrate` is unambiguously specified to protect the hydration lifecycle. ```typescript // app/routes/dashboard.tsx import { Suspense } from "react"; import { Await } from "react-router"; import type { Route } from "./+types/dashboard"; import { fetchUserData, fetchMetrics } from "~/services/dashboard.server"; // Good: Return raw object with streaming promise directly supported by Single Fetch export async function loader({ request }: Route.LoaderArgs) { const user = await fetchUserData(request); const metricsPromise = fetchMetrics(request); // Non-blocking deferred stream return { user, metrics: metricsPromise, }; } // Good: Explicit hydration behavior if clientLoader coordinates with initial document export async function clientLoader({ serverLoader }: Route.ClientLoaderArgs) { const data = await serverLoader(); return data; } // Invariant: Required when clientLoader must participate in initial page load clientLoader.hydrate = false as const; // Good: Strongly typed ComponentProps from generated module export default function Dashboard({ loaderData }: Route.ComponentProps) { const { user, metrics } = loaderData; return ( <main> <h1>Welcome, {user.name}</h1> <Suspense fallback={<div>Loading analytics...</div>}> <Await resolve={metrics}> {(resolvedMetrics) => ( <ul> {resolvedMetrics.map((metric, idx) => ( <li key={idx}>{metric}</li> ))} </ul> )} </Await> </Suspense> </main> ); } ```

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 architectural boundaries for React Router 7 Framework Mode applications using Single Fetch. Mandates the use of generated route module types (+types), prevents hydration mismatches across server-to-client loader transitions, and guarantees correct streaming deferred data consumption via turbo-stream serialization. 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.hydrate, and Returning Legacy JSON Responses in Single Fetch 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.hydrate, and Returning Legacy JSON Responses in Single Fetch	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 from the typegen module `./+types/<route-filename>` (e.g., `import type { Route } from './+types/dashboard'`) for `Route.ComponentProps`, `Route.LoaderArgs`, `Route.ActionArgs`, and `Route.ClientLoaderArgs`.

Engineers MUST ALWAYS import Route types from the typegen module `./+types/<route-filename>` (e.g., `import type { Route } from './+types/dashboard'`) for `Route.ComponentProps`, `Route.LoaderArgs`, `Route.ActionArgs`, and `Route.ClientLoaderArgs`.

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.