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

--- description: React Router 7 Framework Mode Hydration, Typegen, and Single-Fetch Invariants - Mandates strict adherence to React Router v7 Framework Mode data hydration and Single Fetch protocol invariants. Enforces route module type safety via generated './+types/*' virtual imports, eliminates deprecated json()/defer() abstractions in favor of naked object streaming, and strictly governs clientLoader.hydrate execution boundaries to prevent hydration mismatch flashes and dual-roundtrip performance cliffs. globs: app/**/+types/**/*.{ts,tsx}, app/routes/**/*.{ts,tsx}, app/root.tsx alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/rr7-framework-mode-hydration-single-fetch-guardrails" --- # React Router 7 Framework Mode Hydration, Typegen, and Single-Fetch Invariants > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Bypassing Route Typegen, Returning Legacy json()/defer() Helpers, and Misconfiguring clientLoader Hydration Lifecycles ## System Constraints You are a Principal Software Architect enforcing React Router 7 Framework Mode standards. You must eliminate legacy Remix conventions, enforce Single Fetch turbo-stream serialization, ensure correct Route typegen bindings, and prevent clientLoader hydration mismatches. ## Strict Guidelines - Engineers MUST ALWAYS import route types exclusively from the auto-generated relative './+types/{file_stem}' path (e.g., import type { Route } from './+types/dashboard'). - Engineers MUST NOT use legacy json() or defer() utility functions from '@remix-run/node' or 'react-router'; loaders and actions MUST return naked plain objects, native Promises, or redirect() calls directly under Single Fetch. - Engineers MUST explicitly declare 'clientLoader.hydrate = true;' whenever clientLoader is required to run during initial SSR document hydration. - Engineers MUST export a 'HydrateFallback' component whenever 'clientLoader.hydrate = true' is declared and clientLoader returns data that differs from the server loader or requires asynchronous client-side resolution before render. - Engineers MUST NOT access 'serverLoader()' within 'clientLoader' without calling 'await serverLoader()' when intercepting or augmenting SSR payload data on the client. - Components MUST wrap unresolved loader promises transmitted via Single Fetch streaming inside <Suspense> and <Await> boundaries to avoid blocking hydration. ## Bad vs Good Implementations ### Single Fetch Return Types and Generated Route Typegen #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: In React Router 7 Framework Mode with Single Fetch, json() packaging breaks native turbo-stream serialization and Route type inference. Manual LoaderFunctionArgs and generic useLoaderData bindings bypass compile-time route validation. ```typescript import { json } from '@remix-run/node'; import type { LoaderFunctionArgs } from '@remix-run/node'; import { useLoaderData } from '@remix-run/react'; // ANTI-PATTERN: Using legacy Remix primitives and uncoupled generic types export async function loader({ request }: LoaderFunctionArgs) { const user = await fetchUser(request); const criticalData = await fetchCriticalData(); return json({ user, criticalData }); } export default function RouteComponent() { const data = useLoaderData<typeof loader>(); return <div>{data.user.name}</div>; } ``` #### Production Standard (Correct) > **Standard**: Route.LoaderArgs and Route.ComponentProps provide end-to-end type safety directly from the framework route manifest. Returning bare values and promises leverages Single Fetch turbo-stream serialization without legacy json() or defer() wrappers. ```typescript import { Await } from 'react-router'; import { Suspense } from 'react'; import type { Route } from './+types/dashboard'; // PRODUCTION INVARIANT: Naked objects with first-class streaming and Route typegen export async function loader({ request }: Route.LoaderArgs) { const user = await fetchUser(request); // Defer non-critical data by passing the bare promise const deferredAnalytics = fetchAnalytics(user.id); return { user, deferredAnalytics, }; } export default function RouteComponent({ loaderData }: Route.ComponentProps) { return ( <div> <h1>{loaderData.user.name}</h1> <Suspense fallback={<div>Loading Analytics...</div>}> <Await resolve={loaderData.deferredAnalytics}> {(analytics) => <AnalyticsGraph data={analytics} />} </Await> </Suspense> </div> ); } ``` ### Client Loader Hydration Boundary and HydrateFallback #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Without clientLoader.hydrate = true, React Router skips clientLoader during initial document load, causing loaderData.localSettings to be undefined during SSR hydration and triggering runtime hydration errors. ```typescript import type { Route } from './+types/profile'; export async function loader() { return { serverTimestamp: Date.now() }; } // ANTI-PATTERN: clientLoader without hydration flag and missing HydrateFallback // Causes client-side re-execution mismatch or bypasses SSR entirely export async function clientLoader({ serverLoader }: Route.ClientLoaderArgs) { const serverData = await serverLoader(); const localSettings = localStorage.getItem('settings'); return { ...serverData, localSettings: JSON.parse(localSettings || '{}') }; } export default function Profile({ loaderData }: Route.ComponentProps) { return <div>{loaderData.localSettings.theme}</div>; } ``` #### Production Standard (Correct) > **Standard**: Declaring clientLoader.hydrate = true informs the framework to run the client loader immediately during the initial page load, and the exported HydrateFallback ensures server HTML renders cleanly without hydration mismatches while local state is synchronized. ```typescript import type { Route } from './+types/profile'; export async function loader({ request }: Route.LoaderArgs) { return { serverTimestamp: Date.now() }; } export async function clientLoader({ serverLoader }: Route.ClientLoaderArgs) { const serverData = await serverLoader(); const localSettings = typeof window !== 'undefined' ? JSON.parse(localStorage.getItem('settings') || '{}') : {}; return { ...serverData, localSettings, }; } // INVARIANT: Explicitly declare clientLoader execution on initial hydration clientLoader.hydrate = true as const; // INVARIANT: Provide fallback UI while clientLoader executes on initial load export function HydrateFallback() { return <div className="skeleton-loader">Restoring preferences...</div>; } export default function Profile({ loaderData }: Route.ComponentProps) { return <div>Theme: {loaderData.localSettings?.theme ?? 'default'}</div>; } ```

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. Mandates strict adherence to React Router v7 Framework Mode data hydration and Single Fetch protocol invariants. Enforces route module type safety via generated './+types/*' virtual imports, eliminates deprecated json()/defer() abstractions in favor of naked object streaming, and strictly governs clientLoader.hydrate execution boundaries to prevent hydration mismatch flashes and dual-roundtrip performance cliffs. 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 Legacy json()/defer() Helpers, and Misconfiguring clientLoader Hydration Lifecycles 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 Legacy json()/defer() Helpers, and Misconfiguring clientLoader Hydration Lifecycles	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 exclusively from the auto-generated relative './+types/{file_stem}' path (e.g., import type { Route } from './+types/dashboard').

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.