React 19 useActionState & Optimistic Update Idempotent Replay Standard

--- description: React 19 useActionState & Optimistic Update Idempotent Replay Standard - Enforces strict synchronization between React 19 useActionState, useOptimistic, and server actions. Prevents orphaned client-side UI drift and state inconsistency during transient network partitions, server rejections, and retry storms by binding client-generated idempotency keys with deterministic rollback boundaries. 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-use-action-state-optimistic-replay-invariants" --- # React 19 useActionState & Optimistic Update Idempotent Replay Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Unreconciled Optimistic State with Non-Idempotent Server Actions Causing Ghost UI Drift ## System Constraints You are a Principal Frontend Architect enforcing strict React 19 state synchronization invariants. You must mandate that all mutations combining useActionState with useOptimistic use deterministic result envelopes, client-generated idempotency tokens, and unthrowable error handlers to guarantee that optimistic state transitions roll back cleanly during network partitions or transient 5xx rejections. ## Strict Guidelines - Engineers MUST ALWAYS return a structured result envelope ({ success: boolean, data?: T, error?: ActionError, idempotencyKey: string }) from Server Actions passed to useActionState instead of throwing unhandled exceptions across the action boundary. - Engineers MUST generate a unique, cryptographically random idempotencyKey on the client for each optimistic dispatch and propagate it through both the optimistic reducer and the server action payload. - Engineers MUST NOT maintain decoupled parallel useState primitives to track optimistic state that can desynchronize from useActionState results during transient failures. - Code SHOULD leverage useOptimistic exclusively with an immutable update pattern that cleanly derives UI state strictly from the canonical state provided by useActionState. - Components NEVER render optimistic mutations as permanent or non-retryable without verifying server-side acknowledgment matching the original idempotencyKey. ## Bad vs Good Implementations ### Naive useOptimistic with Thrown Errors and Decoupled State vs Idempotent Reconciled Envelope #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Throwing inside server actions causes unhandled rejection boundaries in React 19 transitions, risking UI freeze. Decoupling useState from useOptimistic without useActionState guarantees orphaned state during partial failures and lacks idempotency keys for distributed safety. ```typescript import React, { useState, useOptimistic } from 'react'; // ANTI-PATTERN: Server action throws, optimistic state decouples, no idempotency key async function updateTitleAction(title: string) { 'use server'; if (Math.random() > 0.5) throw new Error('Network partition failure'); return { title }; } export function TitleEditor({ initialTitle }: { initialTitle: string }) { const [title, setTitle] = useState(initialTitle); const [optimisticTitle, setOptimisticTitle] = useOptimistic( title, (_current, next: string) => next ); return ( <form action={async (formData: FormData) => { const nextTitle = formData.get('title') as string; // DRIFT BUG: If updateTitleAction rejects, optimisticTitle will rollback // but local state error recovery is ad-hoc, leaves unhandled promise rejections, // and lacks retry reconciliation keys. setOptimisticTitle(nextTitle); const result = await updateTitleAction(nextTitle); setTitle(result.title); }} > <input name="title" defaultValue={optimisticTitle} /> <button type="submit">Save</button> </form> ); } ``` #### Production Standard (Correct) > **Standard**: Uses useActionState to manage canonical action cycles without throwing. Employs a client-generated UUID idempotency key attached to formData. useOptimistic seamlessly falls back to canonical state if the action returns success: false, preventing orphaned client UI state. ```typescript import React, { useActionState, useOptimistic, startTransition } from 'react'; interface ActionResult<T> { success: boolean; data: T | null; error: string | null; idempotencyKey: string; } interface TaskState { title: string; lastSyncedIdempotencyKey: string; } // INVARIANT: Server actions return structured envelopes, never throw across boundaries async function updateTitleServerAction( _prevState: ActionResult<TaskState>, formData: FormData ): Promise<ActionResult<TaskState>> { 'use server'; const title = (formData.get('title') as string) ?? ''; const idempotencyKey = (formData.get('idempotencyKey') as string) ?? ''; try { // Simulated upstream service call using idempotencyKey if (!title.trim()) { return { success: false, data: null, error: 'Title cannot be empty', idempotencyKey }; } return { success: true, data: { title, lastSyncedIdempotencyKey: idempotencyKey }, error: null, idempotencyKey }; } catch (err) { return { success: false, data: null, error: err instanceof Error ? err.message : 'Transient server error', idempotencyKey }; } } export function TaskEditor({ initialTitle }: { initialTitle: string }) { const initialState: ActionResult<TaskState> = { success: true, data: { title: initialTitle, lastSyncedIdempotencyKey: 'init' }, error: null, idempotencyKey: 'init' }; const [state, formAction, isPending] = useActionState(updateTitleServerAction, initialState); // INVARIANT: Optimistic state is derived synchronously from canonical action state const [optimisticState, setOptimistic] = useOptimistic( state.data?.title ?? initialTitle, (_current, next: string) => next ); const handleClientSubmit = (formData: FormData) => { const nextTitle = (formData.get('title') as string) ?? ''; const idempotencyKey = crypto.randomUUID(); formData.set('idempotencyKey', idempotencyKey); startTransition(async () => { setOptimistic(nextTitle); await formAction(formData); }); }; return ( <form action={handleClientSubmit}> <input name="title" defaultValue={optimisticState} disabled={isPending} /> <button type="submit" disabled={isPending}> {isPending ? 'Syncing...' : 'Save'} </button> {state.error && <p role="alert" className="text-destructive">{state.error}</p>} </form> ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React 19 useActionState & Optimistic Update Idempotent Replay Standard

React 19 useActionState & Optimistic Update Idempotent Replay Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces strict synchronization between React 19 useActionState, useOptimistic, and server actions. Prevents orphaned client-side UI drift and state inconsistency during transient network partitions, server rejections, and retry storms by binding client-generated idempotency keys with deterministic rollback boundaries. 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: Unreconciled Optimistic State with Non-Idempotent Server Actions Causing Ghost UI Drift 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	Unreconciled Optimistic State with Non-Idempotent Server Actions Causing Ghost UI Drift	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 return a structured result envelope ({ success

Engineers MUST ALWAYS return a structured result envelope ({ success: boolean, data?: T, error?: ActionError, idempotencyKey: string }) from Server Actions passed to useActionState instead of throwing unhandled exceptions across the action boundary.

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.