React Router 7 Framework Mode Hydration & Single-Fetch Boundaries

--- description: React Router 7 Framework Mode Hydration & Single-Fetch Boundaries - Governs hydration integrity, single-fetch streaming contracts, and route module typegen in React Router 7 Framework Mode. Mandates native turbo-stream promise passing over legacy defer wrappers, explicit clientLoader.hydrate execution flags, and generated Route type constraints. globs: app/**/*.{ts,tsx}, react-router.config.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/rr7-framework-hydration-single-fetch-standard" --- # React Router 7 Framework Mode Hydration & Single-Fetch Boundaries > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Using legacy Remix defer() wrappers, un-hydrated clientLoaders, and un-typed route exports that cause client-server serialization desynchronization and hydration mismatches. ## System Constraints You are a Principal Software Architect enforcing React Router 7 Framework Mode hydration safety, typegen conformance, and Single Fetch architectural boundaries. You must prevent hydration mismatches, ensure streaming contracts utilize Turbo-stream serialization natively without legacy Remix helpers, and mandate type generation imports. ## Strict Guidelines - Engineers MUST ALWAYS import route module types (e.g., Route.LoaderArgs, Route.ComponentProps) strictly from the route-adjacent generated type files at `./+types/<route-filename-without-extension>`. - Engineers MUST NOT use deprecated Remix data helpers such as `defer()`, `json()`, or manual JSON stringification for dates/errors; React Router 7 Single Fetch natively serializes raw Promises, Dates, Maps, Sets, and BigInt via Turbo-stream. - Code MUST export a `HydrateFallback` component in route modules whenever `clientLoader` is declared with `clientLoader.hydrate = true` and performs asynchronous data fetching. - Services MUST return native pending Promises directly within the loader return payload object to enable progressive streaming via `<Suspense>` and `<Await>`. - Components NEVER execute client-only environment access (window, localStorage, document) during initial SSR evaluation; client-specific initialization MUST execute inside `clientLoader` or `useEffect` boundaries. ## Bad vs Good Implementations ### React Router 7 Framework Mode Loader and Hydration Contract #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Imports legacy `defer` from deprecated packages, manually stringifies dates instead of using native Turbo-stream serialization, neglects generated `./+types` type definitions, and flags `clientLoader.hydrate = true` without exporting the required `HydrateFallback` component. ```typescript import { defer } from "@remix-run/node"; // DEPRECATED: Legacy Remix helper import { useLoaderData, type LoaderFunctionArgs } from "react-router"; export async function loader({ params }: LoaderFunctionArgs) { const criticalData = await fetchCritical(params.id); const slowDataPromise = fetchStreamingMetrics(params.id); // ANTI-PATTERN: defer() is obsolete in RR7 Single Fetch; // Manual ISO date stringification destroys native turbo-stream deserialization return defer({ criticalData: { ...criticalData, fetchedAt: new Date().toISOString() }, slowData: slowDataPromise, }); } // ANTI-PATTERN: Enabling clientLoader hydration without a HydrateFallback causes visual flash and hydration mismatch export async function clientLoader({ serverLoader }: { serverLoader: () => Promise<any> }) { const cached = await getLocalCache(); return cached ?? (await serverLoader()); } clientLoader.hydrate = true; export default function RouteComponent() { const data = useLoaderData() as any; // ANTI-PATTERN: Untyped data bypasses typegen return <div>{data.criticalData.title}</div>; } ``` #### Production Standard (Correct) > **Standard**: Employs `./+types/dashboard` for compile-time safety, natively returns streamable promises and Date objects via Single Fetch, correctly couples `clientLoader.hydrate = true` with a `HydrateFallback`, and resolves streaming data cleanly using React 19 `<Suspense>` and `<Await>`. ```typescript import { Suspense } from "react"; import { Await } from "react-router"; import type { Route } from "./+types/dashboard"; export async function loader({ params }: Route.LoaderArgs) { const criticalData = await fetchCritical(params.id); // NATIVE STREAMING: Raw promises and Dates are serialized automatically by RR7 Single Fetch const slowDataPromise = fetchStreamingMetrics(params.id); return { criticalData: { ...criticalData, fetchedAt: new Date(), // Deserialized directly as a Date instance }, slowData: slowDataPromise, }; } export async function clientLoader({ serverLoader, }: Route.ClientLoaderArgs) { const cached = await getLocalCache(); if (cached) return cached; return await serverLoader(); } clientLoader.hydrate = true as const; // MANDATORY: HydrateFallback prevents client-server mismatch when clientLoader executes during SSR hydration export function HydrateFallback() { return <div className="skeleton-loader" aria-busy="true">Loading dashboard...</div>; } export default function RouteComponent({ loaderData }: Route.ComponentProps) { return ( <main> <h1>{loaderData.criticalData.title}</h1> <time>{loaderData.criticalData.fetchedAt.toLocaleDateString()}</time> <Suspense fallback={<div>Loading dynamic metrics...</div>}> <Await resolve={loaderData.slowData}> {(resolvedMetrics) => <MetricsDisplay data={resolvedMetrics} />} </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. Governs hydration integrity, single-fetch streaming contracts, and route module typegen in React Router 7 Framework Mode. Mandates native turbo-stream promise passing over legacy defer wrappers, explicit clientLoader.hydrate execution flags, and generated Route type constraints. 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: Using legacy Remix defer() wrappers, un-hydrated clientLoaders, and un-typed route exports that cause client-server serialization desynchronization and hydration mismatches. 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	Using legacy Remix defer() wrappers, un-hydrated clientLoaders, and un-typed route exports that cause client-server serialization desynchronization and hydration mismatches.	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 (e.g., Route.LoaderArgs, Route.ComponentProps) strictly from the route-adjacent generated type files at `./+types/<route-filename-without-extension>`.

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.