React 19 Server cache() Request Lifespan & State Leakage Guardrail

--- description: React 19 Server cache() Request Lifespan & State Leakage Guardrail - Enforces deterministic, request-scoped memoization boundaries for React 19's server-side cache() utility across React Server Component (RSC) execution graphs. Prevents cross-request state leakage, memory bloat, and stale data propagation caused by persistent module-level closures or unmemoized asynchronous dispatch. Mandates referential equality discipline and pure functional boundaries when deriving data within server environments. globs: src/app/**/*.{ts,tsx}, src/server/**/*.{ts,tsx}, src/lib/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react19-cache-request-boundary-invariant" --- # React 19 Server cache() Request Lifespan & State Leakage Guardrail > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Global Module-Level Memoization or Unbound Closures Leaking Cross-Request Server State ## System Constraints You are a Principal Engineer enforcing React 19 Request-Scoped cache() Lifespan Invariants. You must ensure that `react.cache()` is exclusively utilized to memoize operations within the lifespan of a single HTTP server request and RSC render pass. Prohibit global mutable maps, dynamic runtime instantiation of `cache()` inside component bodies, and parameter serialization bugs that cross tenant boundaries. ## Strict Guidelines - Engineers MUST ALWAYS declare `cache()` wrapper functions at the module root level rather than inline within component render bodies or request handlers. - Engineers MUST NOT use custom global in-memory maps, LRU stores, or ambient variables to replicate request-scoped deduplication, as they breach isolation across concurrent requests. - Code MUST pass only primitive values or stably serialized references into cached functions, as React's `cache()` uses `Object.is` for argument comparison. - Services MUST ensure that functions wrapped in `cache()` remain pure with respect to the input arguments and do not mutate ambient request contexts. - Components NEVER instantiate `cache()` inside render passes, which results in a new cache bucket per render pass and completely invalidates deduplication across the sub-tree. - Engineers MUST NOT rely on React `cache()` for persistent, long-lived cross-request data sharing; use persistent stores (e.g., Redis, HTTP Cache headers, CDN) for multi-request lifespan storage. ## Bad vs Good Implementations ### Module-Level cache() vs. Inline and Mutable State Anti-Pattern #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using a mutable global Map leaks user data across entirely different user requests and tenants, causing security violations and memory leaks. Re-instantiating `cache()` within the component render function allocates a new cache instance on each invocation, destroying memoization benefits across sibling components. ```typescript import { cache } from 'react'; // ANTI-PATTERN: Global in-memory cache leaks data across concurrent user requests const globalUserStore = new Map<string, any>(); export async function getUserProfile(userId: string) { if (globalUserStore.has(userId)) { return globalUserStore.get(userId); } const res = await fetch(`https://api.internal/users/${userId}`); const data = await res.json(); globalUserStore.set(userId, data); return data; } // ANTI-PATTERN: Defining cache inside a server component re-instantiates on every call export async function UserCard({ userId }: { userId: string }) { const getCachedUser = cache(async (id: string) => { const res = await fetch(`https://api.internal/users/${id}`); return res.json(); }); const user = await getCachedUser(userId); return <div>{user.name}</div>; } ``` #### Production Standard (Correct) > **Standard**: Declaring `getCachedUserProfile` at the module root via `cache()` ensures that multiple Server Components rendered in the same request share identical resolved promises without re-fetching, while React naturally clears the cache bucket at the end of the request. ```typescript import { cache } from 'react'; import 'server-only'; interface UserProfile { id: string; name: string; role: string; } // IMMUTABLE INVARIANT: Module-level cache bound strictly to the current request lifecycle export const getCachedUserProfile = cache(async (userId: string): Promise<UserProfile> => { const res = await fetch(`https://api.internal/users/${userId}`, { headers: { Accept: 'application/json' } }); if (!res.ok) { throw new Error(`Failed to fetch user ${userId}: ${res.statusText}`); } return res.json(); }); export async function UserCard({ userId }: { userId: string }) { // Deterministic, deduplicated per-request execution const user = await getCachedUserProfile(userId); return <div>{user.name}</div>; } ``` ### Object Identity Invalidation in cache() Parameters #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: React's `cache()` utilizes shallow `Object.is` equality on arguments. Passing fresh object literals `{ accountId, includeMetrics: false }` produces distinct references on every call, nullifying deduplication across sibling Server Components. ```typescript import { cache } from 'react'; // ANTI-PATTERN: Cache arguments are compared using Object.is export const getAccountDetails = cache(async (params: { accountId: string; includeMetrics: boolean }) => { const res = await fetch(`https://api.internal/accounts/${params.accountId}?metrics=${params.includeMetrics}`); return res.json(); }); export async function AccountBadge({ accountId }: { accountId: string }) { // Object literal instantiation creates a new reference on every call, bypassing the cache const details = await getAccountDetails({ accountId, includeMetrics: false }); return <span>{details.balance}</span>; } ``` #### Production Standard (Correct) > **Standard**: Deconstructing parameters into primitive types allows React's internal `Object.is` check to successfully hit the memoized promise across any component within the same RSC request tree. ```typescript import { cache } from 'react'; import 'server-only'; // IMMUTABLE INVARIANT: Use primitive scalar arguments for stable Object.is comparisons export const getAccountDetails = cache(async (accountId: string, includeMetrics: boolean = false) => { const res = await fetch(`https://api.internal/accounts/${accountId}?metrics=${includeMetrics}`); if (!res.ok) { throw new Error(`Failed fetching account: ${res.status}`); } return res.json(); }); export async function AccountBadge({ accountId }: { accountId: string }) { // Primitive string and boolean types guarantee Object.is referential matching const details = await getAccountDetails(accountId, false); return <span>{details.balance}</span>; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React 19 Server cache() Request Lifespan & State Leakage Guardrail

React 19 Server cache() Request Lifespan & State Leakage Guardrail defines an industrial-grade behavioral standard for frontend engineering. Enforces deterministic, request-scoped memoization boundaries for React 19's server-side cache() utility across React Server Component (RSC) execution graphs. Prevents cross-request state leakage, memory bloat, and stale data propagation caused by persistent module-level closures or unmemoized asynchronous dispatch. Mandates referential equality discipline and pure functional boundaries when deriving data within server environments. 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: Global Module-Level Memoization or Unbound Closures Leaking Cross-Request Server State 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	Global Module-Level Memoization or Unbound Closures Leaking Cross-Request Server State	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 declare `cache()` wrapper functions at the module root level rather than inline within component render bodies or request handlers.

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.