React Router 7 Framework Mode Hydration, Typegen, and Data Boundaries

--- description: React Router 7 Framework Mode Hydration, Typegen, and Data Boundaries - Enforces strict adherence to React Router 7 Framework Mode single-fetch architecture, generated route type boundaries, and streaming hydration invariants. Prevents hydration mismatches, data waterfall regressions, and broken SSR promise serialization caused by legacy Remix patterns. globs: app/**/*.{ts,tsx}, src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-router-7-hydration-typegen-guardrails" --- # React Router 7 Framework Mode Hydration, Typegen, and Data Boundaries > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Bypassing Typegen with Deprecated json() Utilities and Misconfigured clientLoader.hydrate Triggers ## System Constraints You are a Principal Software Architect enforcing React Router 7 Framework Mode standards. Mandate exact typegen module imports, single-fetch native object returns, and correct hydration lifecycles. Reject deprecated Remix legacy APIs (such as json(), defer(), SerializeFrom) and misconfigured clientLoader.hydrate overrides. ## Strict Guidelines - Engineers MUST ALWAYS type route components, loaders, and actions using generated route types strictly imported from `./+types/<route-filename>` (e.g., `import type { Route } from './+types/my-route';`). - Engineers MUST NOT use deprecated legacy Remix response helpers like `json()`, `defer()`, or manual `SerializeFrom<typeof loader>` types; React Router 7 Single Fetch natively serializes raw JavaScript objects, Dates, Maps, Sets, and Promises via turbo-stream. - Engineers MUST NOT set `clientLoader.hydrate = true` unless implementing an explicit client-cache-first strategy or offline progressive web app, as this forces the clientLoader to re-execute during initial SSR hydration and creates rendering flash/waterfalls. - Code MUST consume streaming loader promises using `<Suspense>` paired with `React.use()` or `<Await>` boundaries, never blocking the synchronous component render phase on unresolved server promises. - Components MUST NOT access browser-only globals (such as `window`, `localStorage`, or `document`) during the initial synchronous render pass; browser-specific side effects MUST be contained within `clientLoader`, `useEffect`, or guarded with hydration status flags. ## Bad vs Good Implementations ### Route Module Typegen and Streaming Data Contract #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using json() or defer() violates RR7 Single Fetch turbo-stream semantics. Manual or any-typing ignores the native typegen system (`./+types/<file>`). Setting clientLoader.hydrate = true forces the browser to discard or re-request SSR data during page load, creating waterfalls. Accessing window directly causes hydration mismatches. ```typescript // DEPRECATED / BROKEN: Legacy Remix patterns in React Router 7 import { json, type LoaderFunctionArgs } from "@remix-run/node"; import { useLoaderData } from "@remix-run/react"; export async function loader({ request }: LoaderFunctionArgs) { const userPromise = fetchUser(request); // Anti-pattern: json() / defer() wrappers break RR7 Single Fetch streaming return json({ userPromise }); } // Anti-pattern: Setting hydrate=true unnecessarily causes double-fetch during hydration export async function clientLoader({ serverLoader }: any) { return serverLoader(); } clientLoader.hydrate = true; export default function BadRoute() { const data = useLoaderData<any>(); // Untyped or manually inferred return <div>{window.location.pathname}</div>; // Hydration mismatch crash } ``` #### Production Standard (Correct) > **Standard**: Imports generated Route types directly from `./+types/user-profile`. Naked objects are returned directly without `json()`, allowing Promises to stream seamlessly. `clientLoader` does not specify `hydrate = true`, preserving instant SSR paint. Streaming data is safely unwrapped using React 19 `use()` inside a `<Suspense>` boundary. ```typescript // PRODUCTION STANDARD: React Router 7 Framework Mode import { Suspense, use } from "react"; import type { Route } from "./+types/user-profile"; export async function loader({ request }: Route.LoaderArgs) { const criticalData = await fetchCriticalProfile(request); // Native naked objects with streaming promises via single-fetch turbo-stream const deferredReviews = fetchReviewsStream(request); return { criticalData, deferredReviews, }; } // clientLoader only runs on client-side navigations by default export async function clientLoader({ serverLoader }: Route.ClientLoaderArgs) { return await serverLoader(); } // hydrate remains false (default) to preserve initial SSR payload function ReviewsStream({ promise }: { promise: Promise<string[]> }) { const reviews = use(promise); // React 19 streaming promise unwrapping return <ul>{reviews.map((r) => <li key={r}>{r}</li>)}</ul>; } export default function UserProfile({ loaderData }: Route.ComponentProps) { const { criticalData, deferredReviews } = loaderData; return ( <main> <h1>{criticalData.name}</h1> <Suspense fallback={<div>Loading reviews...</div>}> <ReviewsStream promise={deferredReviews} /> </Suspense> </main> ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React Router 7 Framework Mode Hydration, Typegen, and Data Boundaries

React Router 7 Framework Mode Hydration, Typegen, and Data Boundaries defines an industrial-grade behavioral standard for frontend engineering. Enforces strict adherence to React Router 7 Framework Mode single-fetch architecture, generated route type boundaries, and streaming hydration invariants. Prevents hydration mismatches, data waterfall regressions, and broken SSR promise serialization caused by legacy Remix patterns. 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 with Deprecated json() Utilities and Misconfigured clientLoader.hydrate Triggers 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 with Deprecated json() Utilities and Misconfigured clientLoader.hydrate Triggers	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 type route components, loaders, and actions using generated route types strictly imported from `./+types/<route-filename>` (e.g., `import type { Route } from './+types/my-route'

Engineers MUST ALWAYS type route components, loaders, and actions using generated route types strictly imported from `./+types/<route-filename>` (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.