React Router 7 Framework Mode Hydration & Single-Fetch Architecture

--- description: React Router 7 Framework Mode Hydration & Single-Fetch Architecture - Enforces strict adherence to React Router 7 framework mode hydration contracts, single-fetch streaming semantics, and route module typegen. Prevents hydration mismatches, duplicate network waterfalls, and broken serialized state caused by legacy Remix primitives (such as json() or defer()) and misconfigured clientLoader boundaries. globs: app/**/{routes,root}/**/*.{ts,tsx}, app/routes/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/rr7-framework-hydration-single-fetch-guardrail" --- # React Router 7 Framework Mode Hydration & Single-Fetch Architecture > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Bypassing Route Typegen and Mismanaging clientLoader Hydration Boundaries in React Router 7 Single-Fetch ## System Constraints You are a Principal Software Architect enforcing React Router 7 framework-mode standards. Mandate strict adherence to generated `./+types/*` interfaces, Single Fetch turbo-stream serialization, explicit `clientLoader.hydrate` configurations, and suspense-wrapped promise streaming boundaries. Eliminate legacy `@remix-run/*` loader patterns, manual `json()`/`defer()` wraps, and uncoordinated client-side cache hydration mismatches. ## Strict Guidelines - Engineers MUST ALWAYS import route contract types exclusively from the route's co-located typegen file (`import type { Route } from './+types/route-name'`) instead of legacy `@remix-run/*` or manual generic definitions. - Engineers MUST NOT use deprecated `json()` or `defer()` response utilities in Single Fetch mode; raw objects and raw pending Promises MUST be returned directly from `loader` functions. - Engineers MUST set `clientLoader.hydrate = true` ONLY when the client loader explicitly needs to run on initial SSR document load; omitting this flag causes the server loader data to hydrate the component while `clientLoader` runs solely on client navigations. - Components consuming deferred promises from Single Fetch loaders MUST ALWAYS wrap the rendered boundary in `<React.Suspense>` and `<Await>` to prevent catastrophic SSR hydration bailouts. - Engineers MUST NEVER access browser-only APIs (`window`, `localStorage`) inside `loader` or default render paths prior to client-side hydration completion. ## Bad vs Good Implementations ### Route Module Data Loading and Hydration Boundary #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using deprecated json() and defer() breaks React Router 7 Single Fetch turbo-stream wire format. Missing `./+types` prevents compile-time route verification. Omitting `clientLoader.hydrate = true` while expecting `clientLoader` to resolve client cache on initial load leads to hydration mismatches between SSR output and local cache state. ```typescript import { json, defer } from '@remix-run/node'; import { useLoaderData } from '@remix-run/react'; // ANTI-PATTERN: Deprecated Remix utilities, untyped loader, missing +types export async function loader() { const criticalData = await fetchCritical(); const slowData = fetchSlow(); // Unwrapped promise with deprecated defer return defer({ criticalData: json(criticalData), slowData, }); } // ANTI-PATTERN: clientLoader without hydrate flag causing SSR mismatch waterfalls export async function clientLoader({ serverLoader }: any) { const cached = localStorage.getItem('cache'); if (cached) return JSON.parse(cached); return serverLoader(); } export default function RouteComponent() { const data = useLoaderData() as any; return ( <div> <h1>{data.criticalData.title}</h1> {/* ANTI-PATTERN: Consuming promise without Suspense/Await boundary */} <p>{data.slowData.details}</p> </div> ); } ``` #### Production Standard (Correct) > **Standard**: Implements React Router 7 framework-mode standards using Route typegen for LoaderArgs and ComponentProps, returns raw objects/promises compatible with turbo-stream Single Fetch, sets clientLoader.hydrate explicitly, and isolates streaming promises with Suspense and Await boundaries. ```typescript import { Suspense } from 'react'; import { Await } from 'react-router'; import type { Route } from './+types/product'; // GOOD: Direct object and raw promise returns supported natively by Single Fetch export async function loader({ params }: Route.LoaderArgs) { const criticalData = await fetchCritical(params.id); const slowData = fetchSlow(params.id); // Streaming promise via turbo-stream return { criticalData, slowData, }; } // GOOD: Explicitly declared hydration behavior for clientLoader export async function clientLoader({ serverLoader }: Route.ClientLoaderArgs) { return await serverLoader(); } clientLoader.hydrate = true as const; export default function RouteComponent({ loaderData }: Route.ComponentProps) { const { criticalData, slowData } = loaderData; return ( <div> <h1>{criticalData.title}</h1> <Suspense fallback={<p>Loading details...</p>}> <Await resolve={slowData}> {(resolved) => <p>{resolved.details}</p>} </Await> </Suspense> </div> ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React Router 7 Framework Mode Hydration & Single-Fetch Architecture

React Router 7 Framework Mode Hydration & Single-Fetch Architecture defines an industrial-grade behavioral standard for frontend engineering. Enforces strict adherence to React Router 7 framework mode hydration contracts, single-fetch streaming semantics, and route module typegen. Prevents hydration mismatches, duplicate network waterfalls, and broken serialized state caused by legacy Remix primitives (such as json() or defer()) and misconfigured clientLoader 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 Route Typegen and Mismanaging clientLoader Hydration Boundaries in React Router 7 Single-Fetch 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 and Mismanaging clientLoader Hydration Boundaries in React Router 7 Single-Fetch	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 contract types exclusively from the route's co-located typegen file (`import type { Route } from './+types/route-name'`) instead of legacy `@remix-run/*` or manual generic definitions.

Engineers MUST ALWAYS import route contract types exclusively from the route's co-located typegen file (`import type { Route } from './+types/route-name'`) instead of legacy `@remix-run/*` or manual generic definitions.

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.