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

--- description: React Router 7 Framework Mode Hydration, Typegen, and Single-Fetch Boundaries - Enforces strict type safety and architectural invariants for React Router 7 Framework Mode (formerly Remix). Requires utilizing generated route module types (+types), leveraging Single Fetch turbo-stream serialization without legacy json() wrappers, and strictly managing clientLoader hydration lifecycles to prevent flash-of-unstyled-content (FOUC) and hydration mismatches. globs: app/routes/**/*.{ts,tsx}, app/root.tsx alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-router-7-hydration-typegen-boundaries" --- # React Router 7 Framework Mode Hydration, Typegen, and Single-Fetch Boundaries > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Bypassing route typegen, returning manual json() responses, and uncoordinated clientLoader hydration without Fallbacks ## System Constraints You are a Principal Software Architect enforcing React Router 7 Framework Mode invariants. In RR7, Single Fetch is the standard data protocol: manual Response wrapping via json() or defer() is obsolete and forbidden. Route types MUST be imported from the generated relative './+types/{filename}' module. When implementing clientLoader alongside loader, engineers MUST explicitly declare 'clientLoader.hydrate = true' when overriding initial SSR data and MUST provide a 'HydrateFallback' component whenever execution delays the initial document render. ## Strict Guidelines - Engineers MUST ALWAYS import route-specific types (LoaderArgs, ActionArgs, ComponentProps, ClientLoaderArgs) from the virtual route module './+types/<route_filename>'. - Engineers MUST NOT use legacy 'json()' or 'defer()' helpers from '@remix-run/node' or 'react-router'; raw JavaScript objects, Dates, Promises, Sets, Maps, and Errors must be returned directly over Single Fetch. - Engineers MUST explicitly define 'clientLoader.hydrate = true as const' if 'clientLoader' is intended to run during initial document hydration. - Engineers MUST export a 'HydrateFallback' component when 'clientLoader.hydrate = true' performs asynchronous operations that block the initial view. - Code MUST consume 'serverLoader()' within 'clientLoader' instead of duplicating server fetches or triggering orphaned network waterfalls. - Components NEVER cast 'useLoaderData<any>()' or write manual loader return types; components MUST type their props using 'Route.ComponentProps'. ## Bad vs Good Implementations ### React Router 7 Route Module Data Loading and Hydration Boundary #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using json() serialization is deprecated in RR7 Single Fetch, which natively serializes complex types via turbo-stream. Skipping route typegen eliminates static checks. Defining a clientLoader without 'clientLoader.hydrate = true' causes the clientLoader to be ignored on initial page load, and the absence of Route.ComponentProps forces unsafe type assertions. ```typescript import { json } from "@remix-run/node"; // Anti-pattern: Deprecated in RR7 Single Fetch import type { LoaderFunctionArgs } from "@remix-run/node"; import { useLoaderData } from "react-router"; export async function loader({ request }: LoaderFunctionArgs) { const user = await fetchUser(request); // Anti-pattern: Unnecessary json() serialization flattens Date and Map objects return json({ user, loadedAt: new Date().toISOString() }); } // Anti-pattern: Missing clientLoader.hydrate annotation leads to skipped client hydration export async function clientLoader() { const localPref = localStorage.getItem("pref"); return { localPref }; } // Anti-pattern: Untyped props / bypass of generated Route types export default function UserRoute() { const data = useLoaderData() as any; return <div>{data.user.name} - {data.loadedAt}</div>; } ``` #### Production Standard (Correct) > **Standard**: Uses RR7 generated './+types/user-profile' for strict static typing. Eliminates manual json() wrappers to leverage native turbo-stream serialization (preserving Date types). Defines 'clientLoader.hydrate = true' with a corresponding 'HydrateFallback' component, while utilizing 'serverLoader()' to avoid redundant data roundtrips. ```typescript import type { Route } from "./+types/user-profile"; // Native Single Fetch: return raw objects, Promises for streaming, Dates, and Sets export async function loader({ params }: Route.LoaderArgs) { const userPromise = fetchUserProfile(params.userId); return { userStream: userPromise, loadedAt: new Date(), }; } // Invariant: Explicitly coordinate client-side hydration with serverLoader export async function clientLoader({ serverLoader }: Route.ClientLoaderArgs) { const serverData = await serverLoader(); const clientPreferences = localStorage.getItem("ui_pref") ?? "default"; return { ...serverData, clientPreferences, }; } clientLoader.hydrate = true as const; // Invariant: HydrateFallback prevents client layout shifts when clientLoader blocks export function HydrateFallback() { return <div className="animate-pulse p-4 text-sm text-neutral-500">Loading session...</div>; } // Invariant: Derive loaderData directly from Route.ComponentProps export default function UserProfile({ loaderData }: Route.ComponentProps) { return ( <main> <h1>Session Active</h1> <time dateTime={loaderData.loadedAt.toISOString()}> {loaderData.loadedAt.toLocaleDateString()} </time> <span data-pref={loaderData.clientPreferences} /> </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 strict type safety and architectural invariants for React Router 7 Framework Mode (formerly Remix). Requires utilizing generated route module types (+types), leveraging Single Fetch turbo-stream serialization without legacy json() wrappers, and strictly managing clientLoader hydration lifecycles to prevent flash-of-unstyled-content (FOUC) and 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, returning manual json() responses, and uncoordinated clientLoader hydration without Fallbacks 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, returning manual json() responses, and uncoordinated clientLoader hydration without Fallbacks	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-specific types (LoaderArgs, ActionArgs, ComponentProps, ClientLoaderArgs) from the virtual route module './+types/<route_filename>'.

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.