React Router 7 Framework Mode: Hydration, ClientLoader Streaming, and Single-Fetch Typegen Guardrails

--- description: React Router 7 Framework Mode: Hydration, ClientLoader Streaming, and Single-Fetch Typegen Guardrails - Enforces single-fetch data semantics, automatic turbo-stream promise streaming, and explicit clientLoader hydration boundaries in React Router 7 framework mode. Prohibits legacy Remix json()/defer() response wrappers and untyped loader signatures, eliminating hydration mismatches, double-fetching, and serialization breakage. 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-framework-hydration-single-fetch" --- # React Router 7 Framework Mode: Hydration, ClientLoader Streaming, and Single-Fetch Typegen Guardrails > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Using Legacy json()/defer() Wrappers, Untyped Route Signatures, and Misconfigured clientLoader Hydration Boundaries ## System Constraints You are a Principal Software Architect enforcing React Router 7 Framework Mode invariants. You must mandate the strict adoption of generated typegen route modules (+types), Single-Fetch turbo-stream return semantics, and robust clientLoader hydration lifecycles. Ensure that no legacy Remix v2 primitives (such as json(), defer(), or manual Response serialization for serializable entities) contaminate route modules. ## Strict Guidelines - Engineers MUST ALWAYS import route module types exclusively from the ambient `./+types/<route-filename>` generated path (e.g., `Route.LoaderArgs`, `Route.ComponentProps`, `Route.ClientLoaderArgs`). - Engineers MUST NOT use `json()`, `defer()`, or manual `new Response(JSON.stringify(...))` wrappers in loaders or actions; React Router 7 Framework Mode native Single-Fetch streams raw objects, Promises, Dates, Maps, Sets, and Errors automatically via turbo-stream. - Engineers MUST NOT await long-running asynchronous tasks directly inside the server loader if they are intended to be streamed; return naked promises within the loader payload and resolve them via `<Suspense>` and `<Await>` in the view. - Code MUST explicitly set `clientLoader.hydrate = true` ONLY when the client-side loader MUST execute during the initial SSR document hydration pass; otherwise, omit it or set it to `false` to consume server-rendered single-fetch data directly. - Code MUST call `await serverLoader()` inside `clientLoader` when decorating or caching server data to guarantee that initial SSR state is properly consumed instead of triggering duplicate network execution. - Components NEVER accept untyped props or manually mapped `SerializeFrom<typeof loader>`; components must accept `Route.ComponentProps` directly to ensure end-to-end type safety across the client-server boundary. ## Bad vs Good Implementations ### React Router 7 Route Module Hydration & Single-Fetch Streaming #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using legacy Remix v2 defer()/json() violates React Router 7 Single-Fetch semantics, breaking native turbo-stream serialization (like Dates, Maps, and raw Promises). Setting `clientLoader.hydrate = true` without calling `serverLoader()` causes an immediate client re-fetch during SSR hydration, destroying server-rendered DOM state and causing flashing hydration mismatches. ```typescript // app/routes/dashboard.tsx import { json, defer } from "@remix-run/node"; // DEPRECATED in RR7 import { useLoaderData, Await } from "@remix-run/react"; import { Suspense } from "react"; // ANTI-PATTERN: Untyped args, using defer() and json() wrappers export async function loader({ request }: any) { const criticalData = await fetchCriticalData(); const slowMetricsPromise = fetchSlowMetrics(); // Breaking Single-Fetch streaming and turbo-stream wire format return defer({ critical: criticalData, metrics: slowMetricsPromise, }); } // ANTI-PATTERN: Overwriting server data on initial hydration without calling serverLoader export async function clientLoader({ request }: any) { const res = await fetch("/api/client-cache"); return res.json(); } clientLoader.hydrate = true; // Forces client execution, discarding SSR HTML data export default function Dashboard() { const data = useLoaderData() as any; return ( <div> <h1>{data.critical.title}</h1> <Suspense fallback={<div>Loading metrics...</div>}> <Await resolve={data.metrics}> {(metrics) => <div>{metrics.totalUsers}</div>} </Await> </Suspense> </div> ); } ``` #### Production Standard (Correct) > **Standard**: Employs React Router 7 Framework Mode typegen via `./+types/dashboard`. Returns naked objects with streamable Promises and standard JS objects (Dates) directly without legacy wrappers. Coordinates `clientLoader` with `await serverLoader()` while setting `clientLoader.hydrate = false` to guarantee optimal hydration efficiency. ```typescript // app/routes/dashboard.tsx import { Suspense } from "react"; import { Await } from "react-router"; import type { Route } from "./+types/dashboard"; import { fetchCriticalData, fetchSlowMetrics } from "~/services/dashboard.server"; // INVARIANT: Native Single-Fetch raw payload return with ambient route typegen export async function loader({ request }: Route.LoaderArgs) { const critical = await fetchCriticalData(); const metricsPromise = fetchSlowMetrics(); // Un-awaited promise for turbo-stream return { critical, metrics: metricsPromise, generatedAt: new Date(), // Native Date serialization supported by turbo-stream }; } // INVARIANT: clientLoader utilizes serverLoader to hydrate without re-fetching export async function clientLoader({ serverLoader }: Route.ClientLoaderArgs) { const serverData = await serverLoader(); const clientTimestamp = performance.now(); return { ...serverData, clientTimestamp, }; } // Omit clientLoader.hydrate or set false unless intentional client-side hydration pass is mandated clientLoader.hydrate = false as const; export default function Dashboard({ loaderData }: Route.ComponentProps) { return ( <div> <h1>{loaderData.critical.title}</h1> <p>Loaded at: {loaderData.generatedAt.toISOString()}</p> <Suspense fallback={<div>Streaming metrics in real-time...</div>}> <Await resolve={loaderData.metrics}> {(resolvedMetrics) => <div>Users: {resolvedMetrics.totalUsers}</div>} </Await> </Suspense> </div> ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React Router 7 Framework Mode: Hydration, ClientLoader Streaming, and Single-Fetch Typegen Guardrails

React Router 7 Framework Mode: Hydration, ClientLoader Streaming, and Single-Fetch Typegen Guardrails defines an industrial-grade behavioral standard for frontend engineering. Enforces single-fetch data semantics, automatic turbo-stream promise streaming, and explicit clientLoader hydration boundaries in React Router 7 framework mode. Prohibits legacy Remix json()/defer() response wrappers and untyped loader signatures, eliminating hydration mismatches, double-fetching, and serialization breakage. 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: Using Legacy json()/defer() Wrappers, Untyped Route Signatures, and Misconfigured 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	Using Legacy json()/defer() Wrappers, Untyped Route Signatures, and Misconfigured 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 module types exclusively from the ambient `./+types/<route-filename>` generated path (e.g., `Route.LoaderArgs`, `Route.ComponentProps`, `Route.ClientLoaderArgs`).

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.