React Router 7 Framework Mode Hydration, Typegen, and Single-Fetch Invariants

--- description: React Router 7 Framework Mode Hydration, Typegen, and Single-Fetch Invariants - Enforces strict React Router 7 framework mode patterns: leveraging route-module typegen via ./+types imports, eliminating deprecated defer() calls in favor of native turbo-stream Single Fetch promises, and safeguarding clientLoader.hydrate execution boundaries against SSR hydration waterfalls and mismatch crashes. 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-hydration-single-fetch-guardrails" --- # React Router 7 Framework Mode Hydration, Typegen, and Single-Fetch Invariants > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Using legacy defer(), manual route typing, or uncoordinated clientLoader.hydrate that triggers client-side re-fetch waterfalls and hydration mismatch bailouts. ## System Constraints You are a Principal Software Architect enforcing React Router 7 (RR7) Framework Mode standards. Mandate zero-waterfall hydration, exact route module typegen adherence via ./+types artifacts, single-fetch streaming conventions, and defensive clientLoader configuration. ## Strict Guidelines - Engineers MUST ALWAYS import route signatures from the auto-generated `./+types/<route_name>` module (e.g., `import type { Route } from './+types/my-route'`) for `Route.LoaderArgs`, `Route.ActionArgs`, `Route.ClientLoaderArgs`, and `Route.ComponentProps`. - Engineers MUST NOT use the legacy `defer()` helper in Single Fetch mode; top-level and nested promises returned in loader responses are automatically streamed via `turbo-stream`. - Engineers MUST wrap all streamed loader promises consumed in JSX inside `<Suspense>` and `<Await resolve={...}>` boundaries with explicit, layout-stable fallbacks to prevent hydration mismatch errors. - Engineers MUST NOT export `clientLoader.hydrate = true` without explicitly handling `serverLoader()` invocation or defining an exported `HydrateFallback` component, preventing discarded SSR HTML and visual flicker. - Services MUST ensure serialized loader data structures adhere to turbo-stream supported primitives (native `Date`, `Map`, `Set`, `BigInt`, `Error`, and `Promise`), avoiding raw non-serializable objects or custom class prototypes without custom serialization hooks. ## Bad vs Good Implementations ### Single Fetch Streaming and Generated Route Types #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: In React Router 7 framework mode with Single Fetch enabled, `defer` is deprecated. Hand-rolled typing abandons the RR7 typegen system (`./+types/*`), and consuming raw streaming promises without `<Suspense>` and `<Await>` triggers immediate React rendering exceptions during client hydration. ```typescript import { defer } from "@remix-run/node"; import { useLoaderData } from "@remix-run/react"; // ANTI-PATTERN: Using deprecated defer(), manual untyped params, missing Route typegen export async function loader({ params }: any) { const critical = await fetchCritical(params.id); const slow = fetchSlowMetrics(params.id); // un-awaited promise return defer({ critical, slow }); } export default function RouteComponent() { const { critical, slow } = useLoaderData() as any; return ( <div> <h1>{critical.title}</h1> {/* ANTI-PATTERN: Consuming promise directly without Suspense/Await boundary */} <div>{slow.metric}</div> </div> ); } ``` #### Production Standard (Correct) > **Standard**: Adheres to RR7 typegen using `Route.LoaderArgs` and `Route.ComponentProps`. Employs Single Fetch native promise streaming without `defer`, safely resolving the background promise via `<Suspense>` and `<Await>` with a stable fallback. ```typescript import { Suspense } from "react"; import { Await } from "react-router"; import type { Route } from "./+types/product-metrics"; export async function loader({ params }: Route.LoaderArgs) { const critical = await fetchCritical(params.id); const slow = fetchSlowMetrics(params.id); // turbo-stream natively streams this return { critical, slow }; } export default function ProductMetricsRoute({ loaderData }: Route.ComponentProps) { return ( <div> <h1>{loaderData.critical.title}</h1> <Suspense fallback={<div className="animate-pulse h-8 w-32 bg-gray-200" />}> <Await resolve={loaderData.slow}> {(resolvedMetrics) => <div>{resolvedMetrics.metric}</div>} </Await> </Suspense> </div> ); } ``` ### Safe clientLoader Hydration and Cache Coordination #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Marking `clientLoader.hydrate = true` without calling `serverLoader()` on initial hydration discards pre-rendered SSR HTML, triggering an immediate re-fetch waterfall and visual layout shifts across user interactions. ```typescript import type { Route } from "./+types/dashboard"; export async function loader() { return { serverData: await fetchInitialData() }; } // ANTI-PATTERN: clientLoader.hydrate runs on initial load, bypassing SSR output completely export async function clientLoader() { const clientData = await fetchClientOnlyCache(); return { serverData: null, clientData }; } clientLoader.hydrate = true; // Blows away SSR HTML and triggers client fetch cascade ``` #### Production Standard (Correct) > **Standard**: Calls `await serverLoader()` inside `clientLoader` to bridge initial server execution with client-side cache decoration, eliminating the hydration flash and providing an explicit `HydrateFallback`. ```typescript import type { Route } from "./+types/dashboard"; export async function loader() { return { initialMetrics: await fetchInitialData() }; } export async function clientLoader({ serverLoader }: Route.ClientLoaderArgs) { // Coordinate with SSR: Read server payload during initial hydration const serverData = await serverLoader(); const cached = await readLocalClientCache(); return { ...serverData, cachedData: cached ?? null, }; } // Invariant: hydrate = true safely leverages serverLoader() to maintain SSR continuity clientLoader.hydrate = true as const; export function HydrateFallback() { return <div className="dashboard-skeleton" />; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React Router 7 Framework Mode Hydration, Typegen, and Single-Fetch Invariants

React Router 7 Framework Mode Hydration, Typegen, and Single-Fetch Invariants defines an industrial-grade behavioral standard for frontend engineering. Enforces strict React Router 7 framework mode patterns: leveraging route-module typegen via ./+types imports, eliminating deprecated defer() calls in favor of native turbo-stream Single Fetch promises, and safeguarding clientLoader.hydrate execution boundaries against SSR hydration waterfalls and mismatch crashes. 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 defer(), manual route typing, or uncoordinated clientLoader.hydrate that triggers client-side re-fetch waterfalls and hydration mismatch bailouts. 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 defer(), manual route typing, or uncoordinated clientLoader.hydrate that triggers client-side re-fetch waterfalls and hydration mismatch bailouts.	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 signatures from the auto-generated `./+types/<route_name>` module (e.g., `import type { Route } from './+types/my-route'`) for `Route.LoaderArgs`, `Route.ActionArgs`, `Route.ClientLoaderArgs`, and `Route.ComponentProps`.

Engineers MUST ALWAYS import route signatures from the auto-generated `./+types/<route_name>` module (e.g., `import type { Route } from './+types/my-route'`) for `Route.LoaderArgs`, `Route.ActionArgs`, `Route.ClientLoaderArgs`, and `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.