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

--- description: React Router 7 Framework Mode Hydration, Typegen, and Single-Fetch Boundaries - Enforces deterministic SSR-to-client hydration invariants in React Router 7 Framework Mode. Mandates strict adherence to Single Fetch promise streaming, generated route module typings, and explicit clientLoader execution policies to prevent rendering waterfalls and hydration drift. globs: app/**/*.{ts,tsx}, app/routes/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-router-7-hydration-single-fetch-guardrail" --- # React Router 7 Framework Mode Hydration, Typegen, and Single-Fetch Boundaries > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Uncontrolled clientLoader Execution and Deprecated defer() Usage Under Single Fetch ## System Constraints You are a Principal Software Architect enforcing React Router 7 (RR7) Framework Mode standards. You must strictly enforce Single Fetch semantics, official typegen route boundaries, and eliminate hydration mismatches or double-fetch waterfalls caused by misconfigured clientLoaders. ## Strict Guidelines - Engineers MUST ALWAYS import route types from the localized typegen virtual directory (e.g., `./+types/<route_name>`) and type component props using `Route.ComponentProps` instead of manual `typeof loader` assertions. - Engineers MUST NOT use the deprecated `json()` or `defer()` response utilities; in React Router 7 Single Fetch mode, loaders MUST return plain objects, and promises intended for streaming MUST be passed directly as object properties. - Engineers MUST NOT define `clientLoader` without explicitly declaring `clientLoader.hydrate = true` if and only if client-side execution is intentionally mandated on initial SSR hydration; otherwise, omit `clientLoader.hydrate` or set it to `false` to prevent discarding server-rendered markup and data. - Components consuming streamed promises MUST wrap downstream consumption inside `<React.Suspense>` and `<Await resolve={...}>` boundaries with a strictly defined fallback to preserve progressive streaming. - Data returned from server `loader` and `action` functions MUST be serializable under `turbo-stream` specifications (supporting native `Date`, `Map`, `Set`, `BigInt`, and `Promise`), and custom serialization wrappers MUST NOT be used. ## Bad vs Good Implementations ### Single Fetch Route Hydration and Streamed Data Typing #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Uses deprecated `defer()` utility, unsafe `as any` type casting bypassing RR7 typegen, and exposes an unconfigured `clientLoader` that triggers an unintended client-side refetch on initial hydration, wiping server-rendered state and causing layout flicker. ```typescript import { defer } from "@remix-run/node"; import { useLoaderData, Await } from "@remix-run/react"; import React from "react"; // ANTI-PATTERN: Using legacy defer(), untyped route hooks, and improper clientLoader export async function loader() { const criticalData = await fetchCriticalData(); const slowPromise = fetchSlowAnalytics(); return defer({ critical: criticalData, analytics: slowPromise, }); } // Flawed: Executing clientLoader on SSR document load without explicit policy // causes hydration mismatch and runs loader twice on initial mount export async function clientLoader({ serverLoader }: { serverLoader: () => Promise<any> }) { return await serverLoader(); } export default function RouteComponent() { const data = useLoaderData() as any; return ( <div> <h1>{data.critical.title}</h1> <React.Suspense fallback={<p>Loading...</p>}> <Await resolve={data.analytics}> {(resolved) => <div>{resolved.views}</div>} </Await> </React.Suspense> </div> ); } ``` #### Production Standard (Correct) > **Standard**: Adheres to React Router 7 framework standards: utilizes `./+types/dashboard` typegen, passes naked promises directly via Single Fetch, explicitly defines `clientLoader.hydrate = false` to guarantee SSR markup is honored without client-side refetch storms, and wires `<Suspense>` with explicit fallback handling. ```typescript import { Suspense } from "react"; import { Await } from "react-router"; import type { Route } from "./+types/dashboard"; import { fetchCriticalData, fetchSlowAnalytics } from "~/services/dashboard.server"; // PRODUCTION INVARIANT: Native Single Fetch object return with typed deferred promise export async function loader({ request }: Route.LoaderArgs) { const critical = await fetchCriticalData(request); const analytics = fetchSlowAnalytics(request); // Naked promise streamed via turbo-stream return { critical, analytics, }; } // Hydrate set to false (or omitted) ensures clientLoader runs ONLY for client transitions export async function clientLoader({ serverLoader }: Route.ClientLoaderArgs) { const data = await serverLoader(); return data; } clientLoader.hydrate = false as const; export default function DashboardRoute({ loaderData }: Route.ComponentProps) { return ( <main> <h1>{loaderData.critical.title}</h1> <Suspense fallback={<p aria-busy="true">Streaming analytics...</p>}> <Await resolve={loaderData.analytics} errorElement={<p>Failed to load analytics.</p>}> {(analytics) => <div>Total Views: {analytics.views}</div>} </Await> </Suspense> </main> ); } ```

Architectural Specification & Invariant Rationale

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

React Router 7 Framework Mode Hydration, Typegen, and Single-Fetch Boundaries defines an industrial-grade behavioral standard for frontend engineering. Enforces deterministic SSR-to-client hydration invariants in React Router 7 Framework Mode. Mandates strict adherence to Single Fetch promise streaming, generated route module typings, and explicit clientLoader execution policies to prevent rendering waterfalls and hydration drift. 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: Uncontrolled clientLoader Execution and Deprecated defer() Usage Under 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	Uncontrolled clientLoader Execution and Deprecated defer() Usage Under 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 from the localized typegen virtual directory (e.g., `./+types/<route_name>`) and type component props using `Route.ComponentProps` instead of manual `typeof loader` assertions.

Engineers MUST ALWAYS import route types from the localized typegen virtual directory (e.g., `./+types/<route_name>`) and type component props using `Route.ComponentProps` instead of manual `typeof loader` assertions.

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.