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

--- description: React Router 7 Framework Mode Hydration, Typegen, and Single-Fetch Invariants - Enforces strict route module typegen contracts, Single Fetch turbo-stream serialization, and explicit clientLoader hydration lifecycle configurations in React Router 7 Framework Mode. Prevents hydration mismatches, double-fetching, and silent serialization failures when streaming deferred promises across SSR boundaries. globs: app/routes/**/*.{ts,tsx}, app/root.tsx, react-router.config.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/rr7-framework-mode-hydration-single-fetch-guardrail" --- # React Router 7 Framework Mode Hydration, Typegen, and Single-Fetch Invariants > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Bypassing Typegen Route Context, Retaining Legacy JSON Responses, and Misconfiguring clientLoader Hydration Boundaries ## System Constraints You are a Principal Software Architect enforcing React Router 7 (RR7) Framework Mode standards. RR7 replaces legacy Remix APIs with Single Fetch (turbo-stream) and route-level type generation. You must reject obsolete Remix patterns (such as json(), defer(), LoaderFunctionArgs without typegen) and mandate deterministic clientLoader hydration semantics. ## Strict Guidelines - Engineers MUST ALWAYS import route types exclusively from the route's generated artifacts: `import type { Route } from './+types/<route-filename>';`. - Engineers MUST NOT use legacy Remix helpers `json()`, `defer()`, or manual `SerializeFrom<typeof loader>` types; RR7 Single Fetch handles raw objects, Promises, Dates, Maps, Sets, and BigInts natively via turbo-stream. - Engineers MUST set `clientLoader.hydrate = true` when `clientLoader` needs to run during initial SSR document hydration, and MUST explicitly call `await serverLoader()` inside `clientLoader` if accessing server data to avoid duplicate fetches or blank states. - Components NEVER use `useLoaderData<typeof loader>()` without passing the generated route type or accessing `Route.ComponentProps['loaderData']`. - Code MUST wrap streamed raw Promises in `<Suspense>` and `<Await>` boundaries, ensuring fallback UI renders during deferred resolution without triggering whole-page hydration failure. - Services MUST ensure any non-serializable objects (functions, non-standard class instances) returned from `loader` are stripped before crossing the SSR-to-client boundary. ## Bad vs Good Implementations ### Route Module Typegen, Single Fetch, and clientLoader Hydration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using legacy `json()` prevents RR7 Single Fetch from using turbo-stream, which natively preserves `Date` objects and raw promises. Manual typing instead of generated `./+types/*` breaks compiler verification of params and loaders. Omitting `clientLoader.hydrate = true` means the clientLoader will not run on initial document hydration, which can lead to stale local cache state or hydration tears. ```typescript import { json } from "@remix-run/node"; // DEPRECATED: Legacy Remix package import { useLoaderData } from "react-router"; // Bad: Manual interface typing decoupled from route manifest typegen export async function loader({ params }: { params: { id: string } }) { const user = await fetchUser(params.id); // Bad: Obsolete json() wrapper breaks Single Fetch turbo-stream serialization return json({ user, timestamp: new Date() }); } // Bad: clientLoader without hydrate property causes silent fallback or double-execution export async function clientLoader({ serverLoader }: any) { return serverLoader(); } export default function UserRoute() { // Bad: Generic type assertion susceptible to hydration drift const { user, timestamp } = useLoaderData() as { user: any; timestamp: string }; return <div>{user.name} logged in at {new Date(timestamp).toISOString()}</div>; } ``` #### Production Standard (Correct) > **Standard**: Imports generated type contracts from `./+types/user-profile`, relies on native return types powered by turbo-stream Single Fetch (preserving `Date` objects without manual parsing), specifies `clientLoader.hydrate = true` to govern client hydration deterministically, and properly wraps the deferred `streamingAnalytics` promise in `<Suspense>` and `<Await>`. ```typescript import { Suspense } from "react"; import { Await } from "react-router"; import type { Route } from "./+types/user-profile"; // Invariant: Native return with Single Fetch turbo-stream preserves types (e.g., Date, Promise) export async function loader({ params }: Route.LoaderArgs) { const criticalData = await fetchCriticalUserData(params.id); const streamingAnalytics = fetchAnalyticsDeferred(params.id); // raw Promise return { criticalData, streamingAnalytics, renderedAt: new Date(), // turbo-stream preserves native Date through hydration }; } // Invariant: Explicitly opt-in to client hydration when clientLoader is present export async function clientLoader({ serverLoader }: Route.ClientLoaderArgs) { const serverData = await serverLoader(); const cachedPref = await getClientPreferences(); return { ...serverData, cachedPref }; } clientLoader.hydrate = true as const; // Invariant: Use generated Route.ComponentProps for end-to-end type safety export default function UserProfile({ loaderData }: Route.ComponentProps) { const { criticalData, streamingAnalytics, renderedAt, cachedPref } = loaderData; return ( <main> <h1>{criticalData.name} ({cachedPref?.theme ?? 'system'})</h1> <p>Hydrated at: {renderedAt.toLocaleTimeString()}</p> <Suspense fallback={<div>Loading streaming telemetry...</div>}> <Await resolve={streamingAnalytics}> {(analytics) => <div>Score: {analytics.score}</div>} </Await> </Suspense> </main> ); } ```

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. Enforces strict route module typegen contracts, Single Fetch turbo-stream serialization, and explicit clientLoader hydration lifecycle configurations in React Router 7 Framework Mode. Prevents hydration mismatches, double-fetching, and silent serialization failures when streaming deferred promises across SSR boundaries. 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 Typegen Route Context, Retaining Legacy JSON Responses, and Misconfiguring clientLoader Hydration Boundaries 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 Typegen Route Context, Retaining Legacy JSON Responses, and Misconfiguring clientLoader Hydration Boundaries	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 route's generated artifacts

Engineers MUST ALWAYS import route types exclusively from the route's generated artifacts: `import type { Route } from './+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.