React Router 7 Framework Mode Hydration & Single-Fetch Boundaries

--- description: React Router 7 Framework Mode Hydration & Single-Fetch Boundaries - Enforces architectural invariants for React Router 7 framework mode hydration, strictly governing typegen route module typing, turbo-stream single-fetch data boundaries, and clientLoader hydration lifecycles. Prevents hydration mismatches, unhandled streaming promise rejections, and invalid clientLoader cache collisions. globs: app/routes/**/*.{ts,tsx}, app/root.tsx, react-router.config.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-router-7-hydration-single-fetch-guardrails" --- # React Router 7 Framework Mode Hydration & Single-Fetch Boundaries > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Bypassing Route Module Typegen, Returning Legacy json() Wrappers in Single Fetch, and Misconfiguring clientLoader.hydrate ## System Constraints You are a Principal Software Architect enforcing React Router 7 Framework Mode invariants. You must mandate strict route typegen compliance via `./+types/{filename}`, enforce single-fetch turbo-stream mechanics (no legacy json()/defer() responses), require structured deferred promise resolution using Suspense/Await boundaries, and guarantee hydration safety across clientLoader executions. ## Strict Guidelines - Engineers MUST ALWAYS import route contracts directly from `./+types/[current_file_basename]` (e.g., `import type { Route } from './+types/dashboard'`) and type route components using `Route.ComponentProps`. - Engineers MUST NOT use legacy Remix utilities like `json()`, `defer()`, or manual `Response` serializations in loaders; React Router 7 single-fetch natively serializes raw objects, Promises, Dates, Sets, and Maps via turbo-stream. - Engineers MUST explicitly set `clientLoader.hydrate = true` when `clientLoader` needs to run on initial document hydration (e.g., pulling from local storage or IndexedDB) and call `await serverLoader()` inside `clientLoader` to resolve server-side single-fetch payloads. - Engineers MUST wrap all non-awaited (deferred/streamed) loader promises within `<Suspense>` and `<Await>` boundaries to avert blocking the initial SSR streaming response or triggering React hydration mismatches (Error #418/425). - Components NEVER read client-only environment state (e.g., `window`, `localStorage`, `navigator`) during initial render without an explicit hydration guard or `useEffect` hook. ## Bad vs Good Implementations ### Route Module Single-Fetch Streaming and clientLoader Hydration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Uses legacy `json()` wrapper which breaks RR7 single-fetch native serialization; relies on untyped `any` instead of `./+types` typegen; reads `window` directly in SSR causing React hydration error #418; misconfigures `clientLoader` without `clientLoader.hydrate = true`; fails to resolve streaming promises inside `<Suspense>` and `<Await>`. ```typescript import { json } from '@remix-run/node'; import { useLoaderData } from '@remix-run/react'; // ANTI-PATTERN: Using legacy json() helper in RR7, generic-untyped useLoaderData, // unhandled raw promise in render causing hydration failure, and missing hydrate flag on clientLoader export async function loader() { const criticalData = await fetchCriticalMetrics(); const slowAnalytics = fetchSlowAnalytics(); // Promise return json({ criticalData, slowAnalytics }); } export async function clientLoader({ serverLoader }: any) { // Anti-pattern: clientLoader without `clientLoader.hydrate = true` does not run on hydration, // causing stale client caches to de-sync from SSR. const serverData = await serverLoader(); return { ...serverData, cachedTimestamp: localStorage.getItem('ts') }; } export default function DashboardRoute() { const data = useLoaderData() as any; // Hydration mismatch: accessing window/localStorage on initial render, // and attempting to render raw un-awaited streaming promise directly return ( <div> <h1>{data.criticalData.title}</h1> <span>Rendered at: {window.location.pathname}</span> <div>{data.slowAnalytics.metric}</div> </div> ); } ``` #### Production Standard (Correct) > **Standard**: Adheres strictly to RR7 framework mode: uses `./+types/dashboard` for compile-time safety, returns naked objects leveraging single-fetch turbo-stream serialization, sets `clientLoader.hydrate = true` to govern client-side state merge, and properly nests deferred promises in `<Suspense>` and `<Await>`. ```typescript import { Suspense } from 'react'; import { Await } from 'react-router'; import type { Route } from './+types/dashboard'; // INVARIANT: Native object return for Single Fetch (turbo-stream serializes promises & dates) export async function loader({ request }: Route.LoaderArgs) { const criticalData = await fetchCriticalMetrics(request); const slowAnalytics = fetchSlowAnalytics(request); // Non-awaited Promise for streaming return { criticalData, slowAnalytics, generatedAt: new Date() }; } // INVARIANT: Explicit hydrate flag determines if clientLoader executes during SSR hydration export async function clientLoader({ serverLoader }: Route.ClientLoaderArgs) { const serverData = await serverLoader(); const localPref = typeof window !== 'undefined' ? localStorage.getItem('dashboard_pref') : null; return { ...serverData, localPref }; } clientLoader.hydrate = true as const; export default function DashboardRoute({ loaderData }: Route.ComponentProps) { const { criticalData, slowAnalytics, generatedAt, localPref } = loaderData; return ( <main> <h1>{criticalData.title}</h1> <time dateTime={generatedAt.toISOString()}>{generatedAt.toLocaleDateString()}</time> {localPref && <aside>Preference: {localPref}</aside>} <Suspense fallback={<p>Streaming analytics...</p>}> <Await resolve={slowAnalytics}> {(resolved) => <div>Metric: {resolved.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 invariants for React Router 7 framework mode hydration, strictly governing typegen route module typing, turbo-stream single-fetch data boundaries, and clientLoader hydration lifecycles. Prevents hydration mismatches, unhandled streaming promise rejections, and invalid clientLoader cache collisions. 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 Module Typegen, Returning Legacy json() Wrappers in Single Fetch, and Misconfiguring clientLoader.hydrate 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 Module Typegen, Returning Legacy json() Wrappers in Single Fetch, and Misconfiguring clientLoader.hydrate	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 directly from `./+types/[current_file_basename]` (e.g., `import type { Route } from './+types/dashboard'`) and type route components using `Route.ComponentProps`.

Engineers MUST ALWAYS import route contracts directly from `./+types/[current_file_basename]` (e.g., `import type { Route } from './+types/dashboard'`) and type route components using `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.