React Router 7 Framework Mode Hydration and Single-Fetch Typegen Boundary

--- description: React Router 7 Framework Mode Hydration and Single-Fetch Typegen Boundary - Enforces strict hydration boundaries, Single Fetch turbo-stream execution contracts, and official route-level typegen in React Router 7 Framework Mode. Prohibits deprecated Remix defer() primitives, uncoordinated clientLoader.hydrate overrides, and manual loader type assertions that cause hydration mismatch crashes and network waterfalls. globs: app/**/+types/**/*.{ts,tsx}, app/routes/**/*.{ts,tsx}, app/root.tsx, src/routes/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/rr7-framework-hydration-single-fetch-guard" --- # React Router 7 Framework Mode Hydration and Single-Fetch Typegen Boundary > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Corrupting Single-Fetch Hydration via Legacy defer() Wrappers and Uncoordinated clientLoader Overrides ## System Constraints You are a Principal Software Architect enforcing React Router 7 Framework Mode standards. Mandate strict compliance with Single Fetch serialization, turbo-stream promise boundaries, typegen imports from relative `./+types/`, and deterministic clientLoader hydration semantics. Reject legacy Remix APIs and unsafe client-side state access during hydration. ## Strict Guidelines - Engineers MUST ALWAYS import Route contracts strictly from the relative typegen module (e.g., `import type { Route } from './+types/my-route';`). - Engineers MUST NOT use the legacy `defer()` helper or `SerializeFrom<T>`; in RR7 Single Fetch, streaming is native: return plain Promises directly in the loader object. - Code MUST explicitly set `clientLoader.hydrate = true` ONLY when clientLoader must run on initial document SSR hydration; otherwise, omit it so initial render reads SSR turbo-stream payload. - Services and loaders calling `clientLoader` with `clientLoader.hydrate = true` MUST call and await `serverLoader()` to prevent dropping server-evaluated data during SSR-to-client handoff. - Components NEVER render non-deterministic client-only variables (e.g., `window.innerWidth`, `navigator.userAgent`) directly in the initial render tree without a `<ClientOnly>` guard or an initial hydration check. ## Bad vs Good Implementations ### React Router 7 Streaming and ClientLoader Hydration Guard #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Uses the deprecated Remix `defer()` API which interferes with React Router 7 Single Fetch turbo-stream serialization, lacks typegen module imports, misses `clientLoader.hydrate = true` which causes inconsistent hydration execution, and accesses `window` directly during SSR rendering. ```typescript import { defer } from "@remix-run/node"; // DEPRECATED in RR7 Framework Mode import { useLoaderData } from "react-router"; export async function loader() { const criticalData = await fetchCritical(); const streamPromise = fetchSlowAnalytics(); // BUG: defer() breaks RR7 Single Fetch turbo-stream protocol return defer({ criticalData, streamPromise }); } // BUG: clientLoader without hydrate flag and without serverLoader() triggers hydration mismatch export async function clientLoader({ serverLoader }: any) { const clientCache = localStorage.getItem("analytics"); if (clientCache) return JSON.parse(clientCache); return serverLoader(); } export default function RouteComponent() { // BUG: Missing typegen typing; unsafe type assertion const { criticalData, streamPromise } = useLoaderData() as any; return ( <div> <h1>{criticalData.title}</h1> {/* BUG: Direct window access causes hydration mismatch */} <span>Client Viewport: {window.innerWidth}px</span> </div> ); } ``` #### Production Standard (Correct) > **Standard**: Implements Route typegen via `./+types/dashboard`, streams raw promises using RR7 Single Fetch semantics, correctly pairs `clientLoader` with `clientLoader.hydrate = true` while awaiting `serverLoader()`, and isolates client-only properties via `useEffect` to guarantee zero hydration mismatches. ```typescript import { Suspense, useState, useEffect } from "react"; import { Await } from "react-router"; import type { Route } from "./+types/dashboard"; export async function loader({ request }: Route.LoaderArgs) { const criticalData = await fetchCritical(request); // Direct bare promise streaming supported natively via turbo-stream Single Fetch const analyticsPromise = fetchSlowAnalytics(request); return { criticalData, analyticsPromise, }; } // Explicitly enforce hydration handoff behavior export async function clientLoader({ serverLoader }: Route.ClientLoaderArgs) { // When hydrate = true, clientLoader runs on initial document load; // MUST await serverLoader() to prevent discarding SSR stream const serverData = await serverLoader(); return { ...serverData, cachedTimestamp: Date.now(), }; } clientLoader.hydrate = true as const; export default function DashboardRoute({ loaderData }: Route.ComponentProps) { const { criticalData, analyticsPromise } = loaderData; const [isClient, setIsClient] = useState(false); useEffect(() => { setIsClient(true); }, []); return ( <main> <h1>{criticalData.title}</h1> <Suspense fallback={<div>Loading streaming analytics...</div>}> <Await resolve={analyticsPromise}> {(analytics) => <section>{analytics.totalVisits}</section>} </Await> </Suspense> {isClient && <span>Client Viewport: {window.innerWidth}px</span>} </main> ); } ```

Architectural Specification & Invariant Rationale

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

React Router 7 Framework Mode Hydration and Single-Fetch Typegen Boundary defines an industrial-grade behavioral standard for frontend engineering. Enforces strict hydration boundaries, Single Fetch turbo-stream execution contracts, and official route-level typegen in React Router 7 Framework Mode. Prohibits deprecated Remix defer() primitives, uncoordinated clientLoader.hydrate overrides, and manual loader type assertions that cause hydration mismatch crashes and network waterfalls. 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: Corrupting Single-Fetch Hydration via Legacy defer() Wrappers and Uncoordinated clientLoader Overrides 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	Corrupting Single-Fetch Hydration via Legacy defer() Wrappers and Uncoordinated clientLoader Overrides	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 strictly from the relative typegen module (e.g., `import type { Route } from './+types/my-route'

Engineers MUST ALWAYS import Route contracts strictly from the relative typegen module (e.g., `import type { Route } from './+types/my-route';`).

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.