React 19 Async Context Propagation and Suspension Boundary Standard

--- description: React 19 Async Context Propagation and Suspension Boundary Standard - Enforces request-scoped promise memoization and granular suspension boundary hierarchy when consuming asynchronous resources via the React 19 use() API in SSR environments. Prevents unmemoized promise re-allocations on re-render ticks from creating infinite suspension loops, stream stalls, and Node.js thread-pool exhaustion. 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-context-suspension-boundary-standard" --- # React 19 Async Context Propagation and Suspension Boundary Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Instantiating Uncached Promises Inline in Component Trees Consumed via use() During SSR Streaming ## System Constraints You are a Principal Engineer enforcing the React 19 Async Context Propagation and Suspension Boundary Standard. You must reject any code that instantiates unmemoized promises in component render paths, passes unstable promises through React Context, or unpacks promises via use() without an enclosing Suspense boundary and request-scoped memoization wrapper. ## Strict Guidelines - Engineers MUST ALWAYS wrap server-rendered async data fetchers with React's cache() utility to ensure stable promise identity across suspension retries. - Engineers MUST NOT instantiate new Promise instances, async IIFEs, or raw fetch calls directly within the body of a React component. - Components consuming a Promise via the React 19 use() API MUST ALWAYS be wrapped in an explicit <Suspense fallback={...}> boundary. - Context providers propagating promises MUST provide cached or module-scoped stable references, never fresh promises created on re-render. - Server streaming renderers MUST configure explicit abort timeouts (e.g., abortDelay / AbortController signals) to fail gracefully when downstream promises fail to resolve. ## Bad vs Good Implementations ### Inline Promise Creation vs Request-Scoped Cached Promise Propagation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Creating a promise directly in the component render body assigns a new reference on every render execution. When the child component suspends using use(promise), React attempts to re-render the parent tree, generating an entirely new promise. This causes an infinite suspension loop, locks the server-side streaming thread pool, and leads to process memory exhaustion. ```typescript import { createContext, use } from 'react'; interface UserData { id: string; name: string; } const UserContext = createContext<Promise<UserData> | null>(null); export function UserProvider({ userId, children }: { userId: string; children: React.ReactNode }) { // ANTI-PATTERN: Creates a brand new promise reference on EVERY render cycle. // When the child suspends during SSR, React re-renders this component, triggering // a new fetch and causing an unbounded suspension loop that stalls the HTTP stream. const userPromise = fetch(`/api/users/${userId}`).then((res) => res.json()); return <UserContext.Provider value={userPromise}>{children}</UserContext.Provider>; } export function UserProfile() { const promise = use(UserContext); if (!promise) throw new Error('Missing UserContext'); // Component suspends on unstable promise, re-triggering parent re-render const user = use(promise); return <div>{user.name}</div>; } ``` #### Production Standard (Correct) > **Standard**: Wrapping data fetching functions with React's cache() stabilizes the promise identity across all render passes within the request lifecycle. Paired with an explicit Suspense boundary, this allows React 19 to pause, stream the fallback shell immediately, and resolve the component when the promise fulfills without re-triggering network calls. ```typescript import { createContext, use, cache, Suspense } from 'react'; interface UserData { id: string; name: string; } // Request-scoped deduplicated promise cache const getUserData = cache(async (userId: string): Promise<UserData> => { const res = await fetch(`https://api.internal/users/${userId}`, { cache: 'no-store' }); if (!res.ok) { throw new Error(`Failed to fetch user data: ${res.statusText}`); } return res.json(); }); const UserContext = createContext<Promise<UserData> | null>(null); export function UserProvider({ userId, children }: { userId: string; children: React.ReactNode }) { // Cache ensures stable promise identity across re-renders and suspension retries const userPromise = getUserData(userId); return <UserContext.Provider value={userPromise}>{children}</UserContext.Provider>; } export function UserProfile() { const promise = use(UserContext); if (!promise) { throw new Error('UserProfile must be used within a UserProvider'); } const user = use(promise); return <div>{user.name}</div>; } export function UserProfileBoundary({ userId }: { userId: string }) { return ( <Suspense fallback={<div role="status" aria-busy="true">Loading user profile...</div>}> <UserProvider userId={userId}> <UserProfile /> </UserProvider> </Suspense> ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React 19 Async Context Propagation and Suspension Boundary Standard

React 19 Async Context Propagation and Suspension Boundary Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces request-scoped promise memoization and granular suspension boundary hierarchy when consuming asynchronous resources via the React 19 use() API in SSR environments. Prevents unmemoized promise re-allocations on re-render ticks from creating infinite suspension loops, stream stalls, and Node.js thread-pool exhaustion. 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 Inline in Component Trees Consumed via use() During SSR Streaming 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 Inline in Component Trees Consumed via use() During SSR Streaming	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 server-rendered async data fetchers with React's cache() utility to ensure stable promise identity across suspension retries.

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.