React Router 7 Framework Mode Hydration & Single-Fetch Route Module Invariants

--- description: React Router 7 Framework Mode Hydration & Single-Fetch Route Module Invariants - Enforces strict typegen-driven route module contracts, deterministic SSR hydration boundaries, and correct clientLoader.hydrate execution flags under React Router 7 Single Fetch mode. Prevents hydration mismatches, double-fetching cascades, and runtime promise resolution failures across turbo-stream boundaries. 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-boundary" --- # React Router 7 Framework Mode Hydration & Single-Fetch Route Module Invariants > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Bypassing Typegen Route Modules and Mishandling clientLoader.hydrate During Single-Fetch Hydration ## System Constraints You are a Principal Software Architect enforcing React Router v7 Framework Mode hydration integrity and typegen correctness. You must mandate strict adherence to `./+types/<route-filename>` type declarations, single-fetch streaming contracts with turbo-stream, and explicit `clientLoader.hydrate` semantics. Never permit deprecated Remix APIs (`json`, `defer`, `LoaderFunctionArgs`, `SerializeFrom`) in RR7 framework codebases. ## Strict Guidelines - Engineers MUST ALWAYS import route contracts strictly from `./+types/<route-filename>` (e.g., `import type { Route } from './+types/dashboard'`) for typing `Route.LoaderArgs`, `Route.ActionArgs`, `Route.ClientLoaderArgs`, and `Route.ComponentProps`. - Engineers MUST NOT import or utilize legacy Remix primitives including `json()`, `defer()`, `LoaderFunctionArgs`, `ActionFunctionArgs`, or `SerializeFrom`; React Router 7 Single Fetch natively handles raw data types, Promises, Dates, Maps, and Errors. - Engineers MUST explicitly set `clientLoader.hydrate = true` if and only if `clientLoader` needs to run during initial document hydration; without this flag, RR7 skips `clientLoader` on initial SSR load and only runs it during client-side navigation transitions. - Engineers MUST ALWAYS invoke `await serverLoader()` inside `clientLoader` when augmenting or caching server data to avoid severing the Single Fetch hydration pipeline or causing unhandled promise rejections. - Components consuming deferred stream promises from Single Fetch loaders MUST wrap downstream consumers in `<Suspense>` and `<Await resolve={...}>` with localized error handling, rather than awaiting raw promises at the top level of the component. - Engineers MUST NOT perform non-deterministic DOM modifications or access `window`/`document` during the initial SSR render phase before hydration completes; state that diverges between client and server must be synchronized via `clientLoader` or standard `useEffect` lifecycle boundaries. ## Bad vs Good Implementations ### React Router 7 Route Module Hydration & Typegen Standard #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The route imports deprecated Remix primitives (`json`, `LoaderFunctionArgs`), breaks Promise streaming by passing promises through `json()`, manually type-casts `useLoaderData`, and declares a `clientLoader` without `clientLoader.hydrate = true` and without calling `serverLoader()`. This induces runtime hydration mismatches and data loss. ```typescript // app/routes/project.$id.tsx import { json } from '@remix-run/node'; // DEPRECATED: RR7 uses raw objects via Single Fetch import type { LoaderFunctionArgs } from '@remix-run/node'; // DEPRECATED: Missing typegen import { useLoaderData } from '@remix-run/react'; export async function loader({ params }: LoaderFunctionArgs) { const project = await fetchProject(params.id); const metricsPromise = fetchMetrics(params.id); // Streaming candidate return json({ project, metrics: metricsPromise }); // BUG: json() serializes Promise to empty object {} } export async function clientLoader({ serverLoader }: any) { // BUG: clientLoader lacks `clientLoader.hydrate = true` // BUG: Does not call or await serverLoader(), starving initial hydration state return { cachedData: localStorage.getItem('project_cache') }; } export default function ProjectRoute() { const data = useLoaderData() as any; // Type-unsafe casting return <div>{data.project.name} - {data.cachedData}</div>; } ``` #### Production Standard (Correct) > **Standard**: Adheres strictly to RR7 framework invariants: uses typegen (`Route.LoaderArgs`, `Route.ComponentProps`), relies on native Single Fetch serialization (preserving `Promise` and `Date`), correctly pairs `clientLoader` with `await serverLoader()`, explicitly enables `clientLoader.hydrate = true`, and wraps streamed data inside `<Suspense>` and `<Await>`. ```typescript // app/routes/project.$id.tsx import { Suspense } from 'react'; import { Await } from 'react-router'; import type { Route } from './+types/project.$id'; export async function loader({ params }: Route.LoaderArgs) { const project = await fetchProject(params.id); // Single Fetch natively streams unresolved Promises via turbo-stream const metrics = fetchMetrics(params.id); return { project, metrics, timestamp: new Date() }; } export async function clientLoader({ serverLoader, params, }: Route.ClientLoaderArgs) { const [serverData, cachedMetadata] = await Promise.all([ serverLoader(), readLocalCache(params.id), ]); return { ...serverData, cachedMetadata, }; } // Mandate execution during initial hydration handoff clientLoader.hydrate = true as const; export default function ProjectRoute({ loaderData }: Route.ComponentProps) { return ( <main> <h1>{loaderData.project.name}</h1> <p>Hydrated At: {loaderData.timestamp.toISOString()}</p> {loaderData.cachedMetadata && <span>Cached: {loaderData.cachedMetadata}</span>} <Suspense fallback={<div>Loading telemetry...</div>}> <Await resolve={loaderData.metrics}> {(metrics) => <div>Active Nodes: {metrics.activeNodes}</div>} </Await> </Suspense> </main> ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React Router 7 Framework Mode Hydration & Single-Fetch Route Module Invariants

React Router 7 Framework Mode Hydration & Single-Fetch Route Module Invariants defines an industrial-grade behavioral standard for frontend engineering. Enforces strict typegen-driven route module contracts, deterministic SSR hydration boundaries, and correct clientLoader.hydrate execution flags under React Router 7 Single Fetch mode. Prevents hydration mismatches, double-fetching cascades, and runtime promise resolution failures across turbo-stream boundaries. 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 Modules and Mishandling clientLoader.hydrate During Single-Fetch 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	Bypassing Typegen Route Modules and Mishandling clientLoader.hydrate During Single-Fetch 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 contracts strictly from `./+types/<route-filename>` (e.g., `import type { Route } from './+types/dashboard'`) for typing `Route.LoaderArgs`, `Route.ActionArgs`, `Route.ClientLoaderArgs`, and `Route.ComponentProps`.

Engineers MUST ALWAYS import route contracts strictly from `./+types/<route-filename>` (e.g., `import type { Route } from './+types/dashboard'`) for typing `Route.LoaderArgs`, `Route.ActionArgs`, `Route.ClientLoaderArgs`, and `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.