React Router 7 Framework Mode Hydration, Typegen & Data Boundary Invariants

--- description: React Router 7 Framework Mode Hydration, Typegen & Data Boundary Invariants - Enforces strict type safety and hydration boundaries in React Router 7 framework mode with Single Fetch enabled. Mandates the use of generated Route types from `./+types/*`, prohibits unawaited clientLoader overrides that break server-to-client streaming, and prevents hydration mismatches caused by leaking server-exclusive Single Fetch primitives into client bundles. 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-hydration-typegen-guardrail" --- # React Router 7 Framework Mode Hydration, Typegen & Data Boundary Invariants > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Bypassing Route Typegen, Misconfiguring clientLoader.hydrate, and Breaking Single Fetch Stream Serialization ## System Constraints You are a Principal Software Architect enforcing zero-defect hydration and data-flow invariants in React Router 7 (Remix v3 transition) Framework Mode. You reject manual loader typing, require generated Route types, mandate exact clientLoader hydration flags, and guarantee clean Single Fetch boundaries across SSR and client navigation. ## Strict Guidelines - Engineers MUST ALWAYS import route module types exclusively from the virtual generated path `./+types/<route-file-name>` (e.g., `import type { Route } from './+types/dashboard';`). - Engineers MUST NOT manually type `loaderData` using arbitrary generics like `useLoaderData<typeof loader>()` or explicit interfaces; use `Route.ComponentProps` or `Route.LoaderArgs`. - Engineers MUST set `clientLoader.hydrate = true` ONLY when the client loader intentionally runs during initial document hydration; otherwise, initial SSR data will be discarded or duplicated. - Engineers MUST ALWAYS call `await serverLoader()` inside `clientLoader` when augmenting SSR data, rather than re-fetching primary server state over raw `fetch` on initial load. - Code MUST handle deferred streaming promises using React 19 `<Suspense>` and standard promises, never wrapping payloads in legacy `defer()` when Single Fetch is enabled. - Components NEVER execute non-deterministic APIs (e.g., `Date.now()`, `crypto.randomUUID()`, `window.matchMedia`) in the render path without guarding inside `useEffect` or deriving from loader data to eliminate hydration mismatches. - Services MUST return raw, serializable JavaScript objects (Dates, BigInt, Errors, Map, Set) directly in loaders, relying on turbo-stream via Single Fetch instead of manual `json()` serialization. ## Bad vs Good Implementations ### React Router 7 Typegen and Hydrated clientLoader with Single Fetch #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The anti-pattern manually serializes data via Response/json() instead of relying on Single Fetch turbo-stream, relies on unsafe type assertions (`as ...`) instead of `./+types/dashboard`, and forgets `clientLoader.hydrate = true` or `serverLoader()` integration, which triggers hydration mismatches and breaks cache continuity. ```typescript // app/routes/dashboard.tsx import { useLoaderData } from "react-router"; // ANTI-PATTERN: Manual loader typing, legacy json() wrapper, // missing clientLoader.hydrate flag causing hydration mismatch export async function loader() { return new Response(JSON.stringify({ user: "Alice", timestamp: new Date() }), { headers: { "Content-Type": "application/json" }, }); } export async function clientLoader({ serverLoader }: any) { // Invariant broken: Omitting clientLoader.hydrate = true while defining // clientLoader prevents this from running on client-side navigations smoothly // or causes double fetches if misconfigured. const data = await fetch("/api/user").then(r => r.json()); return { user: data.user, cached: false }; } export default function Dashboard() { // ANTI-PATTERN: Weakly typed hook bypassing route typegen const data = useLoaderData() as { user: string; timestamp: string }; return <div>Welcome {data.user} at {data.timestamp}</div>; } ``` #### Production Standard (Correct) > **Standard**: Utilizes the official `./+types/dashboard` typegen route module for absolute type safety across loader arguments and component props. Uses Single Fetch automatic serialization (passing raw Date objects), correctly pairs `clientLoader` with `await serverLoader()`, and explicitly specifies `clientLoader.hydrate = true` to preserve hydration integrity. ```typescript // app/routes/dashboard.tsx import type { Route } from "./+types/dashboard"; // Production Invariant: Raw objects with built-in Single Fetch turbo-stream serialization export async function loader({ request }: Route.LoaderArgs) { return { user: "Alice", renderedAt: new Date(), // Date is preserved across wire without stringification }; } // Explicit hydration configuration: Run on initial document load to augment server data export async function clientLoader({ serverLoader }: Route.ClientLoaderArgs) { const serverData = await serverLoader(); const clientPreference = localStorage.getItem("theme") ?? "system"; return { ...serverData, theme: clientPreference, }; } // Mandatory when clientLoader must execute on initial SSR hydration clientLoader.hydrate = true as const; export default function Dashboard({ loaderData }: Route.ComponentProps) { return ( <div> <h1>Welcome {loaderData.user}</h1> <time dateTime={loaderData.renderedAt.toISOString()}> {loaderData.renderedAt.toLocaleDateString()} </time> <span>Theme: {loaderData.theme}</span> </div> ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React Router 7 Framework Mode Hydration, Typegen & Data Boundary Invariants

React Router 7 Framework Mode Hydration, Typegen & Data Boundary Invariants defines an industrial-grade behavioral standard for frontend engineering. Enforces strict type safety and hydration boundaries in React Router 7 framework mode with Single Fetch enabled. Mandates the use of generated Route types from `./+types/*`, prohibits unawaited clientLoader overrides that break server-to-client streaming, and prevents hydration mismatches caused by leaking server-exclusive Single Fetch primitives into client bundles. 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 Breaking Single Fetch Stream 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	Bypassing Route Typegen, Misconfiguring clientLoader.hydrate, and Breaking Single Fetch Stream 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 module types exclusively from the virtual generated path `./+types/<route-file-name>` (e.g., `import type { Route } from './+types/dashboard'

Engineers MUST ALWAYS import route module types exclusively from the virtual generated path `./+types/<route-file-name>` (e.g., `import type { Route } from './+types/dashboard';`).

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.