React Router 7 Framework Mode Hydration & Single-Fetch Boundaries

--- description: React Router 7 Framework Mode Hydration & Single-Fetch Boundaries - Enforces architectural constraints for React Router 7 framework mode hydration, clientLoader caching, and Single Fetch data boundaries. Prevents client-server state desynchronization, double-fetching waterfalls, hydration mismatches, and broken route typegen contracts. globs: app/**/*.{ts,tsx}, src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/rr7-framework-hydration-single-fetch-invariants" --- # React Router 7 Framework Mode Hydration & Single-Fetch Boundaries > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Bypassing Typegen Contracts and Misconfiguring clientLoader Hydration in React Router 7 Single-Fetch ## System Constraints You are a Principal Software Architect enforcing React Router 7 (RR7) Framework Mode standards. Mandate the strict use of route module typegen, correct single-fetch streaming semantics (turbo-stream), and sound clientLoader hydration lifecycles. Ensure code avoids legacy Remix patterns (e.g., json(), defer()) and prevents hydration mismatches. ## Strict Guidelines - Engineers MUST ALWAYS import route types directly from the generated route module `./+types/<route-name>` (e.g., `import type { Route } from './+types/dashboard'`). - Engineers MUST NOT use legacy Remix utilities `json()` or `defer()`; React Router 7 Framework Mode natively serializes naked objects, Promises, Dates, Maps, Sets, and Errors via Single Fetch turbo-stream. - Engineers MUST explicitly export `clientLoader.hydrate = true` when `clientLoader` is required to run on initial client-side hydration, and MUST call `await serverLoader()` to reuse the SSR payload instead of re-fetching from scratch. - Code MUST wrap streamed loader promises in `<Suspense fallback={...}>` and `<Await>` within route components to prevent blocking initial paint and avoid hydration boundary drops. - Components NEVER accept arbitrary loader prop types; components MUST declare their props using `Route.ComponentProps` to enforce full type fidelity with single-fetch return types. - Engineers MUST NOT access `window`, `document`, or client-only APIs in the root of the route module or in loader functions; guards must be isolated in `useEffect` or inside an explicitly gated `clientLoader`. ## Bad vs Good Implementations ### React Router 7 Route Module with Single Fetch Streaming and Client Hydration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Uses deprecated `json()` wrapper which breaks Single Fetch streaming primitives, omits generated `./+types/dashboard` typegen, omits `clientLoader.hydrate = true` which causes execution skipping or unexpected client waterfalls, and fails to handle deferred promises with Suspense/Await. ```typescript import { json } from '@remix-run/node'; // Anti-pattern: Legacy Remix helper import { useLoaderData } from 'react-router'; // Anti-pattern: Manual/untyped loader args and return export async function loader({ request }: any) { const criticalData = await fetchCritical(); const slowData = fetchSlow(); // Intended to stream, but json() serializes eagerly return json({ criticalData, slowData }); } // Anti-pattern: clientLoader defined without hydrate=true, causing hydration mismatch/bailout export async function clientLoader({ serverLoader }: any) { return serverLoader(); } // Anti-pattern: untyped component props missing Route typegen export default function Dashboard() { const data = useLoaderData() as any; return ( <div> <h1>{data.criticalData.title}</h1> <p>{data.slowData.metric}</p> </div> ); } ``` #### Production Standard (Correct) > **Standard**: Adheres to React Router 7 Framework Mode: imports Route typegen, directly returns promises and structured objects without legacy `json()`, uses `clientLoader.hydrate = true` with `serverLoader()` for predictable hydration, and encapsulates streamed data within `Suspense` and `Await`. ```typescript import { Suspense } from 'react'; import { Await } from 'react-router'; import type { Route } from './+types/dashboard'; import { fetchCritical, fetchSlow } from '~/services/api.server'; // Single Fetch: return naked objects; slow promises stream automatically via turbo-stream export async function loader({ request }: Route.LoaderArgs) { const criticalData = await fetchCritical(request); const slowDataPromise = fetchSlow(request); return { criticalData, streamed: { slowData: slowDataPromise, }, }; } // Explicitly designate clientLoader to run during initial SSR hydration export async function clientLoader({ serverLoader }: Route.ClientLoaderArgs) { const serverData = await serverLoader(); return { ...serverData, clientTimestamp: Date.now(), }; } clientLoader.hydrate = true as const; // Fully typed component via typegen export default function Dashboard({ loaderData }: Route.ComponentProps) { return ( <main> <h1>{loaderData.criticalData.title}</h1> <Suspense fallback={<div>Loading metrics...</div>}> <Await resolve={loaderData.streamed.slowData}> {(slowData) => <div>Metric: {slowData.metric}</div>} </Await> </Suspense> </main> ); } ```

Architectural Specification & Invariant Rationale

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

React Router 7 Framework Mode Hydration & Single-Fetch Boundaries defines an industrial-grade behavioral standard for frontend engineering. Enforces architectural constraints for React Router 7 framework mode hydration, clientLoader caching, and Single Fetch data boundaries. Prevents client-server state desynchronization, double-fetching waterfalls, hydration mismatches, and broken route typegen contracts. 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 Contracts and Misconfiguring clientLoader Hydration 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 Typegen Contracts and Misconfiguring clientLoader Hydration 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 types directly from the generated route module `./+types/<route-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.