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 hydration contracts, accurate Route typegen definitions, and safe turbo-stream deserialization under React Router 7 Framework Mode. Prevents full client re-fetches during initial document load, eliminates hydration mismatch traps caused by improper clientLoader.hydrate configurations, and ensures robust deferred streaming boundaries across Single Fetch architectures. globs: app/routes/**/*.{ts,tsx}, app/root.tsx, react-router.config.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-router-v7-hydration-single-fetch-guardrails" --- # React Router 7 Framework Mode Hydration, Typegen, and Single-Fetch Invariants > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Bypassing Single Fetch Streaming with Unsafe clientLoader Re-executions and Raw Response Hydration Mismatches ## System Constraints You are a Principal Software Architect enforcing React Router 7 Framework Mode (Remix v3 evolution) production standards. You must strictly enforce the Single Fetch contract, Route typegen imports (`./+types/<route-filename>`), hydration execution ordering (`clientLoader.hydrate`), and turbo-stream deferred serialization. Reject legacy Remix primitives (`json`, `defer`), untyped route exports, and clientLoaders that unconditionally overwrite server-rendered HTML states. ## Strict Guidelines - Engineers MUST ALWAYS import route types directly from the co-located typegen file (`./+types/<file-name>`) instead of manually typing loaders, actions, and component props. - Engineers MUST NOT export `clientLoader` without setting `clientLoader.hydrate = true` if the route requires client-side caching or fallback hydration on the initial document request; otherwise, the server data is used automatically and the clientLoader is bypassed on document load. - Engineers MUST NEVER invoke `serverLoader()` inside `clientLoader` when `clientLoader.hydrate` is enabled on initial document render without checking `serverLoader()` availability, as Single Fetch serializes data into `window.__reactRouterContext`. - Engineers MUST return raw JavaScript primitives, Promises, Dates, Maps, and Sets directly from `loader` functions rather than wrapping them in `Response` objects or legacy `json()`/`defer()` utilities, leveraging Single Fetch turbo-stream serialization. - Components MUST wrap streamed deferred promises in `<Suspense>` and `<Await>` boundaries, never awaiting raw loader promises in the render cycle or destructuring un-resolved promises directly. ## Bad vs Good Implementations ### Route Module Typegen and Deferred Streaming Hydration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using json() prevents Single Fetch native serialization (turbo-stream). Omitting Route namespace typegen drops compiler guarantees. Defining clientLoader without clientLoader.hydrate = true results in clientLoader running only on client-side SPA navigations, while having it call serverLoader without understanding hydration execution order can trigger hydration mismatches and redundant HTTP requests. ```typescript import { json } from '@remix-run/node'; import { useLoaderData } from 'react-router'; // ANTI-PATTERN: Using deprecated json wrapper in RR7, missing typegen imports, // and misconfiguring clientLoader which destroys server hydration state export async function loader() { return json({ criticalData: 'rendered-on-server', lazyMetric: fetch('https://api.example.com/metric').then((r) => r.json()), }); } export async function clientLoader({ serverLoader }: any) { // Refetches on client mount, causing dual-fetch or layout flash const serverData = await serverLoader(); return { ...serverData, clientTimestamp: Date.now() }; } // Missing clientLoader.hydrate flag export default function RouteComponent() { const data = useLoaderData() as any; return ( <div> <h1>{data.criticalData}</h1> <span>{data.lazyMetric.count}</span> </div> ); } ``` #### Production Standard (Correct) > **Standard**: Leverages RR7 typegen Route.LoaderArgs and Route.ComponentProps. Returns naked objects with native Dates and deferred Promises supported by Single Fetch turbo-stream. Accurately defines clientLoader.hydrate = true to govern initial document execution, and wraps streamed promises in <Suspense> and <Await> boundaries to protect React 19 / RR7 concurrent hydration. ```typescript import { Suspense } from 'react'; import { Await } from 'react-router'; import type { Route } from './+types/dashboard'; // Native Single Fetch: return raw objects, Dates, and bare Promises export async function loader({ request }: Route.LoaderArgs) { return { criticalData: 'rendered-on-server', createdAt: new Date(), // turbo-stream natively retains Date instance lazyMetric: fetch('https://api.example.com/metric').then((r) => r.json() as Promise<{ count: number }>), }; } // Explicitly enforce hydration invariant export async function clientLoader({ serverLoader }: Route.ClientLoaderArgs) { const serverData = await serverLoader(); return { ...serverData, clientHydratedAt: Date.now(), }; } // hydrate = true forces clientLoader execution during initial SSR hydration clientLoader.hydrate = true as const; export default function DashboardRoute({ loaderData }: Route.ComponentProps) { return ( <div> <h1>{loaderData.criticalData}</h1> <time>{loaderData.createdAt.toISOString()}</time> <Suspense fallback={<div>Loading metric...</div>}> <Await resolve={loaderData.lazyMetric}> {(metric) => <span>{metric.count}</span>} </Await> </Suspense> </div> ); } ```

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 hydration contracts, accurate Route typegen definitions, and safe turbo-stream deserialization under React Router 7 Framework Mode. Prevents full client re-fetches during initial document load, eliminates hydration mismatch traps caused by improper clientLoader.hydrate configurations, and ensures robust deferred streaming boundaries across Single Fetch architectures. 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 Single Fetch Streaming with Unsafe clientLoader Re-executions and Raw Response Hydration Mismatches 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 Single Fetch Streaming with Unsafe clientLoader Re-executions and Raw Response Hydration Mismatches	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 (`./+types/<file-name>`) instead of manually typing loaders, actions, and component props.

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.