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 adherence to React Router 7 framework-mode data loading, hydration boundaries, and type generation. Prevents hydration mismatches, duplicate fetches, and broken streaming states caused by legacy Remix primitives (json, defer) and improper clientLoader.hydrate configurations under turbo-stream single-fetch. globs: app/**/{route,root,+*}.{ts,tsx}, app/routes/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/rr7-framework-hydration-single-fetch-boundary" --- # React Router 7 Framework Mode Hydration and Single-Fetch Typegen Boundary > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Legacy Remix v2 Primitives and Unsynchronized clientLoader Hydration in React Router 7 Single-Fetch ## System Constraints You are a Principal Software Architect enforcing React Router 7 Framework Mode hydration safety, strict typegen usage (+types), and Single-Fetch turbo-stream serialization boundaries. Reject any legacy Remix patterns, mismanaged clientLoader hydration policies, or unsafe streaming boundaries. ## Strict Guidelines - Engineers MUST ALWAYS import route types (Route.LoaderArgs, Route.ComponentProps, Route.ClientLoaderArgs) exclusively from relative `./+types/<filename>` generated modules. - Engineers MUST NOT use deprecated Remix v2 wrappers such as `json()` or `defer()`; React Router 7 Single-Fetch natively streams plain objects, promises, Maps, Sets, Dates, and Errors via turbo-stream. - Code MUST explicitly declare `clientLoader.hydrate = true` if and only if `clientLoader` needs to run during the initial page load to augment or override server loader data. - Services MUST call `await serverLoader()` inside `clientLoader` when `clientLoader.hydrate = true` is declared to preserve server-side streaming responses and avoid double-fetching. - Components NEVER render streamed promises outside of `<Suspense>` and `<Await>` boundaries, and must safely type resolved values using `Route.ComponentProps`. ## Bad vs Good Implementations ### React Router 7 Route Module with Single-Fetch & clientLoader Hydration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Uses deprecated Remix v2 `json`/`defer` utilities (which break RR7 Single-Fetch turbo-stream encoding), imports legacy Remix types instead of `./+types`, lacks `clientLoader.hydrate = true` (resulting in missed client state on SSR hydration), and fails to invoke `serverLoader()`, dropping server data entirely. ```typescript import { json, defer } from '@remix-run/node'; import type { LoaderFunctionArgs } from '@remix-run/node'; import { useLoaderData } from '@remix-run/react'; // ANTI-PATTERN: Using deprecated json/defer, legacy Remix types, and unhydrated clientLoader export async function loader({ request }: LoaderFunctionArgs) { const slowData = fetchSlowData(); // Promise return defer({ fastData: 'instant', slowData, }); } // ANTI-PATTERN: Missing clientLoader.hydrate declaration causes clientLoader // to be completely skipped on SSR initial load, causing hydration data drift. export async function clientLoader({ serverLoader }: any) { const cache = localStorage.getItem('client_cache'); return { localState: cache }; } export default function RouteComponent() { const data = useLoaderData<any>(); return <div>{data.fastData}</div>; } ``` #### Production Standard (Correct) > **Standard**: Utilizes RR7 typegen `./+types/dashboard`, leverages native turbo-stream support for rich types (`Date`) and streamed promises without `defer()`, enforces `clientLoader.hydrate = true` while preserving server loader payload via `await serverLoader()`, and properly wraps streaming promises in `<Suspense>` and `<Await>`. ```typescript import { Suspense } from 'react'; import { Await } from 'react-router'; import type { Route } from './+types/dashboard'; // CORRECT: Return plain objects and naked promises directly for turbo-stream single-fetch export async function loader({ request }: Route.LoaderArgs) { return { fastData: 'instant', serverTime: new Date(), slowData: fetchSlowData(), // Naked promise streamed over single fetch }; } // CORRECT: Explicit hydration flag with serverLoader execution export async function clientLoader({ serverLoader }: Route.ClientLoaderArgs) { const serverData = await serverLoader(); const cachedPref = typeof window !== 'undefined' ? localStorage.getItem('pref') : null; return { ...serverData, cachedPref, }; } clientLoader.hydrate = true as const; export default function RouteComponent({ loaderData }: Route.ComponentProps) { return ( <div> <p>Data: {loaderData.fastData}</p> <p>Loaded at: {loaderData.serverTime.toISOString()}</p> <Suspense fallback={<span>Loading deferred segment...</span>}> <Await resolve={loaderData.slowData}> {(resolved) => <span>Resolved: {resolved.value}</span>} </Await> </Suspense> </div> ); } ```

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 adherence to React Router 7 framework-mode data loading, hydration boundaries, and type generation. Prevents hydration mismatches, duplicate fetches, and broken streaming states caused by legacy Remix primitives (json, defer) and improper clientLoader.hydrate configurations under turbo-stream single-fetch. 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: Legacy Remix v2 Primitives and Unsynchronized clientLoader Hydration in React Router 7 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	Legacy Remix v2 Primitives and Unsynchronized clientLoader Hydration in React Router 7 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 (Route.LoaderArgs, Route.ComponentProps, Route.ClientLoaderArgs) exclusively from relative `./+types/<filename>` generated modules.

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.