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

--- description: React Router 7 Framework Mode: Hydration, Single Fetch, and Route Module Typegen Invariants - In React Router 7 Framework Mode, data boundaries rely on Single Fetch architecture backed by turbo-stream serialization and auto-generated route module typegen. Violating hydration lifecycle invariants—such as wrapping naked data returns in legacy Response objects, neglecting clientLoader.hydrate execution semantics, or discarding generated Route types—triggers hydration mismatches, tears down streaming boundaries, and breaks isomorphic rendering. globs: app/**/+types/**/*.{ts,tsx}, 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-v7-framework-hydration-single-fetch" --- # React Router 7 Framework Mode: Hydration, Single Fetch, and Route Module Typegen Invariants > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Bypassing Single Fetch Wire Serialization and Misconfiguring clientLoader.hydrate Lifecycle Boundaries ## System Constraints You are a Principal Software Architect enforcing React Router 7 Framework Mode hydration safety, Single Fetch streaming contracts, and route module typegen. Reject legacy Remix v2 json() wrappers, enforce explicit clientLoader.hydrate contracts, require strict use of ./+types relative imports, and ensure all streaming promises are consumed via Suspense and Await boundaries. ## Strict Guidelines - Engineers MUST ALWAYS import Route module types strictly from the auto-generated relative path `./+types/<route-filename-without-ext>` to guarantee complete LoaderData, ActionData, and Params synchronization. - Engineers MUST NOT wrap loader returns in `json()` or `new Response(JSON.stringify(...))` under React Router 7 Single Fetch; naked objects, native instances (`Date`, `BigInt`, `Map`, `Set`, `Error`), and deferred `Promise` instances MUST be returned directly. - Engineers MUST explicitly set `clientLoader.hydrate = true` if and only if the `clientLoader` is intended to execute during initial SSR document hydration; otherwise, omitting it instructs the runtime to consume serverLoader output without executing clientLoader on the initial load. - Code SHOULD leverage `serverLoader()` inside `clientLoader` when decorating, caching, or augmenting SSR payloads on the client to avoid redundant network fetch waterfalls. - Components NEVER render client-specific primitives (e.g., localStorage, window.matchMedia) during the initial hydration pass; non-deterministic values MUST be deferred to `useEffect` or client-only gates to avoid React hydration mismatch crashes. ## Bad vs Good Implementations ### React Router 7 Loader and ClientLoader Hydration Contract #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using legacy json() breaks Single Fetch turbo-stream serialization, turning native Date instances into strings and preventing direct streaming of promises. Omitting Route module typegen from `./+types` sacrifices compile-time route validation. Omitting `clientLoader.hydrate = true` prevents clientLoader from executing during initial page load when client-side state synchronization is required. ```typescript import { json } from '@remix-run/node'; // Anti-pattern: Legacy Remix v2 import import { Await, useLoaderData } from 'react-router'; // Anti-pattern: Manual parameter typing bypasses route typegen export async function loader({ params }: { params: { id: string } }) { const userPromise = fetchUser(params.id); const timestamp = new Date(); // Anti-pattern: json() serializes Date to string and breaks turbo-stream streaming return json({ userPromise, timestamp }); } // Anti-pattern: Missing clientLoader.hydrate flag; loader will not execute on hydration, // leading to cache inconsistency when components expect client-side state. export async function clientLoader({ serverLoader }: any) { const data = await serverLoader(); localStorage.setItem('cached-user', JSON.stringify(data)); return data; } export default function RouteComponent() { // Anti-pattern: Untyped or manually cast loader data const { userPromise, timestamp } = useLoaderData() as any; return ( <div> {/* Anti-pattern: timestamp is string due to json(), crashing if treated as Date */} <p>Loaded at: {timestamp.toISOString()}</p> <Await resolve={userPromise}> {(user) => <div>{user.name}</div>} </Await> </div> ); } ``` #### Production Standard (Correct) > **Standard**: Employs strict Route typegen via `./+types/user-profile`. Naked objects are returned directly to let React Router 7's Single Fetch encode native data structures and streaming promises via turbo-stream. `clientLoader.hydrate = true` formally declares execution on SSR hydration, and `<Suspense>` guarantees proper boundary streaming without hydration mismatches. ```typescript import { Suspense } from 'react'; import { Await } from 'react-router'; import type { Route } from './+types/user-profile'; export async function loader({ params }: Route.LoaderArgs) { const userPromise = fetchUser(params.id); // Direct return: Single Fetch natively preserves Date, Error, Map, Set, BigInt, and Promise return { userPromise, timestamp: new Date(), }; } // Explicitly mandate execution during SSR hydration to warm local storage or memory cache export async function clientLoader({ serverLoader }: Route.ClientLoaderArgs) { const serverData = await serverLoader(); return { ...serverData, cachedLocally: true, }; } clientLoader.hydrate = true as const; export default function RouteComponent({ loaderData }: Route.ComponentProps) { const { userPromise, timestamp } = loaderData; return ( <div> <p>Loaded at: {timestamp.toISOString()}</p> <Suspense fallback={<div>Loading user profile...</div>}> <Await resolve={userPromise}> {(user) => <div>{user.name}</div>} </Await> </Suspense> </div> ); } ```

Architectural Specification & Invariant Rationale

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

React Router 7 Framework Mode: Hydration, Single Fetch, and Route Module Typegen Invariants defines an industrial-grade behavioral standard for frontend engineering. In React Router 7 Framework Mode, data boundaries rely on Single Fetch architecture backed by turbo-stream serialization and auto-generated route module typegen. Violating hydration lifecycle invariants—such as wrapping naked data returns in legacy Response objects, neglecting clientLoader.hydrate execution semantics, or discarding generated Route types—triggers hydration mismatches, tears down streaming boundaries, and breaks isomorphic rendering. 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 Wire Serialization and Misconfiguring clientLoader.hydrate Lifecycle Boundaries 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 Wire Serialization and Misconfiguring clientLoader.hydrate Lifecycle Boundaries	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 module types strictly from the auto-generated relative path `./+types/<route-filename-without-ext>` to guarantee complete LoaderData, ActionData, and Params synchronization.

Engineers MUST ALWAYS import Route module types strictly from the auto-generated relative path `./+types/<route-filename-without-ext>` to guarantee complete LoaderData, ActionData, and Params synchronization.

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.