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 typegen contracts, single-fetch streaming boundaries, and correct clientLoader hydration mechanics in React Router 7 Framework Mode. Eliminates double-fetch penalties, serialization drift across the turbo-stream wire protocol, and SSR hydration mismatches. globs: app/**/{route,root,+*}.{ts,tsx}, app/routes/**/*.{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-data-boundary-standard" --- # React Router 7 Framework Mode Hydration, Typegen, and Single-Fetch Invariants > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Bypassing Route Typegen, Misusing clientLoader.hydrate, and Emitting Legacy Remix defer() Primitives ## System Constraints You are a Principal Software Architect enforcing React Router 7 Framework Mode hydration safety, Single Fetch streaming contracts, and route module typegen standards. You must strictly prevent legacy Remix paradigms, improper clientLoader hydration overrides, unhandled streaming boundaries, and manual type annotations. ## Strict Guidelines - Engineers MUST ALWAYS import route types directly from the co-located `./+types/[route-file-name]` virtual module for loaders, actions, and component props. - Engineers MUST NOT import from legacy packages (`@remix-run/node`, `@remix-run/react`, `@remix-run/router`); all core framework primitives MUST come from `react-router`. - Engineers MUST NOT use legacy Remix `defer()` utility; React Router 7 Single Fetch natively handles raw promises via `turbo-stream` serialization. - Engineers MUST NOT export `clientLoader.hydrate = true` unless the server loader output is explicitly bypassed or augmented during the initial HTML document hydration. Setting `hydrate = true` unnecessarily triggers a redundant client-side network request immediately after SSR. - Engineers MUST wrap all streamed loader promises in `<Suspense>` and `<Await>` components with explicit `errorElement` or `fallback` boundaries inside the UI layer. - Components NEVER read non-serializable browser globals (`window`, `localStorage`, `document`) during top-level render or loader execution without explicit client-side environment gating or `HydrationBoundary` isolation. ## Bad vs Good Implementations ### Route Module Definition with Streaming and clientLoader Hydration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Imports legacy @remix-run packages, manually casts typings with `any` instead of RR7 route typegen, utilizes deprecated `defer()`, forces a client-side refetch on initial load via `clientLoader.hydrate = true`, and renders `<Await>` without a `<Suspense>` wrapper causing hydration failures. ```typescript import { defer } from "@remix-run/node"; import { useLoaderData, Await } from "@remix-run/react"; // ANTI-PATTERN: Manual typing without typegen, using legacy Remix defer(), // and setting clientLoader.hydrate = true causing immediate double-fetch on load export async function loader() { const criticalData = await fetchCritical(); const slowStreamedData = fetchSlowStream(); return defer({ criticalData, slowStreamedData }); } export async function clientLoader({ serverLoader }: any) { const data = await serverLoader(); return { ...data, clientTimestamp: Date.now() }; } // WRONG: Forces clientLoader to run during initial SSR document load clientLoader.hydrate = true; export default function DashboardView() { const data = useLoaderData<any>(); return ( <div> <h1>{data.criticalData.title}</h1> {/* WRONG: Missing Suspense wrapper around Await */} <Await resolve={data.slowStreamedData}> {(resolved: any) => <div>{resolved.details}</div>} </Await> </div> ); } ``` #### Production Standard (Correct) > **Standard**: Leverages RR7 virtual typegen (`Route.LoaderArgs`, `Route.ComponentProps`), streams raw promises via standard Single Fetch, avoids spurious SSR re-fetching by omitting `clientLoader.hydrate = true`, and properly wraps streaming promises in `<Suspense>` with fallback and error boundaries. ```typescript import { Suspense } from "react"; import { Await } from "react-router"; import type { Route } from "./+types/dashboard"; // INVARIANT: Native Single Fetch promise streaming via turbo-stream export async function loader({ request }: Route.LoaderArgs) { const criticalData = await fetchCritical(request); // Raw promise passes directly through turbo-stream boundary const slowStreamedData = fetchSlowStream(request); return { criticalData, slowStreamedData, }; } // clientLoader runs only for client-side SPA navigations unless hydrate is needed export async function clientLoader({ serverLoader }: Route.ClientLoaderArgs) { const serverData = await serverLoader(); return { ...serverData, cachedLocally: true, }; } // Explicit: Do not set clientLoader.hydrate = true unless bypassing SSR data intentionally export default function DashboardView({ loaderData, }: Route.ComponentProps) { const { criticalData, slowStreamedData } = loaderData; return ( <main> <h1>{criticalData.title}</h1> <Suspense fallback={<p>Streaming details...</p>}> <Await resolve={slowStreamedData} errorElement={<p>Failed loading details.</p>} > {(resolved) => <div>{resolved.details}</div>} </Await> </Suspense> </main> ); } ```

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 typegen contracts, single-fetch streaming boundaries, and correct clientLoader hydration mechanics in React Router 7 Framework Mode. Eliminates double-fetch penalties, serialization drift across the turbo-stream wire protocol, and SSR hydration mismatches. 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, Misusing clientLoader.hydrate, and Emitting Legacy Remix defer() Primitives 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, Misusing clientLoader.hydrate, and Emitting Legacy Remix defer() Primitives	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 co-located `./+types/[route-file-name]` virtual module for loaders, actions, and component props.

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.