React Router 7 Framework Mode Hydration and Single-Fetch Invariants

--- description: React Router 7 Framework Mode Hydration and Single-Fetch Invariants - Enforces strict typegen route module typing, turbo-stream native serialization, and explicit clientLoader hydration boundaries in React Router 7 Framework Mode. Prevents hydration mismatch bugs, duplicate network roundtrips, and stream serialization breakage caused by legacy Remix v2 patterns like json() wrappers and manual generic types. 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-single-fetch-production-standard" --- # React Router 7 Framework Mode Hydration and Single-Fetch Invariants > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Unsafe clientLoader Hydration Overrides and Legacy json() Wrappers Breaking Single Fetch Serialization ## System Constraints You are a Principal Software Architect enforcing React Router 7 (RR7) Framework Mode standards. Mandate zero-boilerplate Single Fetch data serialization, correct route module typegen consumption (+types), strict clientLoader.hydrate execution contracts, and streaming data hydration boundaries. ## Strict Guidelines - Engineers MUST ALWAYS import route types directly from the co-located typegen file (`import type { Route } from "./+types/<file-name>";`) and annotate route functions as `export async function loader({ params }: Route.LoaderArgs)` and component as `export default function Component({ loaderData }: Route.ComponentProps)`. - Engineers MUST NOT wrap loader return values in legacy `json()`, `defer()`, or `Response.json()` utilities; RR7 Single Fetch uses `turbo-stream` and expects raw plain objects, Dates, Maps, Sets, or raw unresolved Promises. - Engineers MUST NOT type `useLoaderData` with explicit generics (`useLoaderData<typeof loader>()`); loader data must be consumed directly via typed component props (`Route.ComponentProps`) or argument-free `useLoaderData()` within the route boundary. - Engineers MUST export a `HydrateFallback` component whenever `clientLoader.hydrate = true` is declared on a route that performs asynchronous client hydration, ensuring deterministic SSR DOM hydration. - Engineers MUST ensure that any Promise returned by `loader` intended for streaming is consumed via React `<Suspense>` and React Router `<Await>`, with proper error boundaries attached to prevent uncaught streaming rejections. - Components NEVER execute browser-dependent side effects (such as reading `window` or `localStorage`) during initial render evaluation without an isHydrated guard or `useEffect`, preventing React 19 hydration mismatch errors. ## Bad vs Good Implementations ### Route Module Data Loading and Hydration Boundary #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The legacy code uses deprecated Remix v2 wrappers (json, defer, LoaderFunctionArgs), explicitly serializes Dates to strings instead of relying on turbo-stream native types, manually types useLoaderData, and enables clientLoader.hydrate = true without providing a HydrateFallback component, resulting in hydration desynchronization. ```typescript import { json, defer, useLoaderData } from "@remix-run/node"; // Legacy Remix imports import type { LoaderFunctionArgs } from "@remix-run/node"; export async function loader({ request, params }: LoaderFunctionArgs) { const criticalData = await fetchCritical(params.id); const slowDataPromise = fetchSlow(params.id); // BAD: Using legacy json/defer wrappers in RR7 Framework mode with Single Fetch return defer({ critical: criticalData, slow: slowDataPromise, timestamp: new Date().toISOString() // BAD: Unnecessarily serializing Date to string }); } // BAD: clientLoader.hydrate is true without HydrateFallback exported, risking hydration mismatch export async function clientLoader({ serverLoader }: any) { const cached = localStorage.getItem("cache"); if (cached) return JSON.parse(cached); return serverLoader(); } clientLoader.hydrate = true as const; export default function RouteComponent() { // BAD: Manual generic typing instead of RR7 Typegen Route.ComponentProps const data = useLoaderData<typeof loader>(); return <div>{data.timestamp}</div>; } ``` #### Production Standard (Correct) > **Standard**: Leverages React Router 7 Framework Mode Typegen (`Route.*`), drops `json()`/`defer()` in favor of direct Single Fetch raw object returns preserving native `Date` instances, supplies `HydrateFallback` for `clientLoader.hydrate = true`, and resolves streamed promises with `<Suspense>` and `<Await>`. ```typescript import { Suspense } from "react"; import { Await } from "react-router"; import type { Route } from "./+types/dashboard"; export async function loader({ params }: Route.LoaderArgs) { const critical = await fetchCritical(params.id); const slowPromise = fetchSlow(params.id); // Streaming promise natively supported by turbo-stream // GOOD: Return raw objects with native types (Date, Map, Set, Promises) for Single Fetch return { critical, slow: slowPromise, createdAt: new Date() }; } export async function clientLoader({ serverLoader }: Route.ClientLoaderArgs) { return serverLoader(); } // Opt into client-side hydration execution explicitly when required clientLoader.hydrate = true as const; // GOOD: Provide HydrateFallback when clientLoader runs during initial HTML hydration export function HydrateFallback() { return <div className="animate-pulse">Loading route data...</div>; } export default function DashboardRoute({ loaderData }: Route.ComponentProps) { // GOOD: Type-safe props directly derived from Route.ComponentProps via +types return ( <main> <h1>{loaderData.critical.title}</h1> <time dateTime={loaderData.createdAt.toISOString()}> {loaderData.createdAt.toLocaleDateString()} </time> <Suspense fallback={<p>Streaming details...</p>}> <Await resolve={loaderData.slow}> {(slow) => <div>{slow.details}</div>} </Await> </Suspense> </main> ); } ```

Architectural Specification & Invariant Rationale

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

React Router 7 Framework Mode Hydration and Single-Fetch Invariants defines an industrial-grade behavioral standard for frontend engineering. Enforces strict typegen route module typing, turbo-stream native serialization, and explicit clientLoader hydration boundaries in React Router 7 Framework Mode. Prevents hydration mismatch bugs, duplicate network roundtrips, and stream serialization breakage caused by legacy Remix v2 patterns like json() wrappers and manual generic types. 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: Unsafe clientLoader Hydration Overrides and Legacy json() Wrappers Breaking Single Fetch Serialization 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	Unsafe clientLoader Hydration Overrides and Legacy json() Wrappers Breaking Single Fetch Serialization	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 co-located typegen file (`import type { Route } from "./+types/<file-name>"

Engineers MUST ALWAYS import route types directly from the co-located typegen file (`import type { Route } from "./+types/<file-name>";`) and annotate route functions as `export async function loader({ params }: Route.LoaderArgs)` and component as `export default function Component({ loaderData }: 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.