React 19 Async Resource Hydration & Promise De-duplication Standard

--- description: React 19 Async Resource Hydration & Promise De-duplication Standard - Mandates deterministic microtask de-duplication and memory eviction for async resources unwrapped via React 19's `use()` API. Enforces request-scoped cache boundaries and WeakMap-backed promise registries to prevent infinite suspension loops and server memory leaks during concurrent streaming hydration. globs: src/**/*.{ts,tsx}, app/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-19-async-hydration-promise-dedupe" --- # React 19 Async Resource Hydration & Promise De-duplication Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Instantiating Uncached Promises in Render or Using Unbounded Global Caches with use() ## System Constraints You are a Principal Engineer enforcing the React 19 Async Resource Hydration & Promise De-duplication Standard. You must reject any pattern that instantiates floating promises in component bodies or maintains unbounded, non-request-scoped caches for the `use()` hook. Ensure all unwrapped promises are de-duplicated per render cycle, strictly isolated between SSR streams to prevent cross-request memory bleeding, and pruned via deterministic garbage collection. ## Strict Guidelines - Engineers MUST ALWAYS wrap data-fetching functions consumed by React 19 `use(promise)` with `React.cache()` on the server or an explicit request-scoped de-duplication container. - Engineers MUST NOT instantiate raw Promise objects inside component bodies or custom hooks during render execution, as this forces infinite suspense loops. - Engineers MUST NOT use module-level, unbounded `Map` or `Set` registries to cache promises, as this leaks memory across concurrent server rendering streams. - Components NEVER unwrap an untracked promise via `use()` without attaching an explicit `.catch()` handler to the underlying promise to prevent unhandled microtask rejections. - Services MUST ensure that client-side cached promises implement deterministic eviction (such as `WeakMap` keys bound to component or query lifecycles) immediately upon unmount or stream resolution. ## Bad vs Good Implementations ### Uncached Promise in Component Render vs. Request-Scoped React.cache() with use() #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Creating or storing promises in a module-level Map during SSR causes memory leaks and cross-request data leaks across concurrent requests. If the promise is instantiated in render without a stable cache, it re-creates the promise on every tick, causing React 19 to suspend indefinitely. ```typescript import { use } from 'react'; // ANTI-PATTERN: Module-level unbounded cache leaks memory across SSR requests; // creating a promise directly in render creates new identities on every render pass. const globalPromiseCache = new Map<string, Promise<UserData>>(); export function UserProfile({ userId }: { userId: string }) { let promise = globalPromiseCache.get(userId); if (!promise) { // Creates runaway heap memory on SSR and leaks cross-tenant state promise = fetch(`/api/users/${userId}`).then(res => res.json()); globalPromiseCache.set(userId, promise); } // When used inside render without deterministic lifecycle or cleanup, // any rejection will bubble as an unhandled microtask error const user = use(promise); return <div>{user.name}</div>; } ``` #### Production Standard (Correct) > **Standard**: Using `React.cache()` guarantees that identical calls with the same arguments return the exact same Promise instance throughout a single render pass or SSR request stream. The references are bound to the request scope, eliminating memory leaks and infinite suspension loops. ```typescript import { use, cache } from 'react'; interface UserData { id: string; name: string; } // GOOD: React.cache creates a per-request de-duplication boundary. // Promises are garbage collected automatically at the end of the SSR stream. const fetchUserData = cache(async (userId: string): Promise<UserData> => { const res = await fetch(`https://api.internal/users/${userId}`, { headers: { 'Content-Type': 'application/json' }, }); if (!res.ok) { throw new Error(`Failed to hydrate user ${userId}: ${res.statusText}`); } return res.json(); }); export function UserProfile({ userId }: { userId: string }) { // Deterministic promise reference de-duplicated per microtask/request const userPromise = fetchUserData(userId); // Safely unwrapped via React 19 use() API const user = use(userPromise); return <div>{user.name}</div>; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React 19 Async Resource Hydration & Promise De-duplication Standard

React 19 Async Resource Hydration & Promise De-duplication Standard defines an industrial-grade behavioral standard for frontend engineering. Mandates deterministic microtask de-duplication and memory eviction for async resources unwrapped via React 19's `use()` API. Enforces request-scoped cache boundaries and WeakMap-backed promise registries to prevent infinite suspension loops and server memory leaks during concurrent streaming hydration. 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: Instantiating Uncached Promises in Render or Using Unbounded Global Caches with use() 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	Instantiating Uncached Promises in Render or Using Unbounded Global Caches with use()	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 wrap data-fetching functions consumed by React 19 `use(promise)` with `React.cache()` on the server or an explicit request-scoped de-duplication container.

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.