React

Performance optimization and architectural patterns for React and Next.js applications. Profile and optimize React and Next.js applications by eliminating network waterfalls, managing bundle size, and reducing unnecessary re-renders.

Modes

Select an execution mode before Step 1:

• Audit mode (default). Profile bundles, waterfalls, and re-renders, and report findings without editing source code.
• Optimize mode. Restructure Server and Client boundaries, stream Suspense trees, split chunks, upgrade action hooks, and apply compiler-safe optimizations.

Reference quick routing

Workflow

Follow these five steps in sequence.

Step 1. Toolchain probe and bottleneck identification

Probe the project runtime, compiler configuration, and performance symptoms before modifying code:

1. Check React version, Next.js version, and compiler configuration across package.json and Next.js config:

   node -e "const fs=require('fs'),p=JSON.parse(fs.readFileSync('package.json','utf8')),d={...p.dependencies,...p.devDependencies},c=['next.config.ts','next.config.mjs','next.config.js'].find(f=>fs.existsSync(f));console.log({react:d.react,next:d.next,compiler:Boolean(d['babel-plugin-react-compiler']||(c&&/reactCompiler\s*:\s*true/.test(fs.readFileSync(c,'utf8'))))})"

2. Run TypeScript compiler diagnostics with Next.js route typegen:

   npx next typegen && npx tsc --noEmit

3. Profile component rendering or network waterfalls to isolate the exact bottleneck.

Completion criterion. .agents/state/react/baseline.json exists on disk with fields react_version, next_version, compiler, tsc_errors (0), perf_metric_name, perf_metric_baseline, perf_metric_threshold, and perf_metric_source. perf_metric_source is one of lighthouse-json, web-vitals-lib, next-bundle-analyzer, or manual-profiler. Attach the raw measurement artifact path to perf_metric_source_path. A baseline without a source artifact is rejected.

Step 2. Rule selection and priority triage

Filter rules by the React version detected in Step 1:

• React 19 or later. All categories apply, including server- and modern action hooks.
• React 18. Skip useActionState and useOptimistic upgrades. Use useTransition for pending states. Retain forwardRef rather than passing ref as standard prop. Skip compiler optimizations when compiler: false.
• React 17 or earlier. Skip all Server Component and Server Action rules. Confine optimizations to bundle-, client-, and rerender- categories.

Record category selection in .agents/state/react/rule-selection.json. Enforce joint security and serialization invariants: every RSC or Server Action change must verify server authorization and Client boundary DTO safety.

Completion criterion. .agents/state/react/rule-selection.json exists on disk with fields react_version and applied_categories matching the project runtime.

Step 3. Reference consultation

Read the specific rule file in references/rules/<prefix>-<name>.md for concrete code implementations, anti-patterns, and mechanical fixes.

Completion criterion. The rule file is inspected and the canonical fix pattern is established before mutating source files.

Step 4. Surgical implementation

Apply minimal code changes to eliminate the bottleneck:

• Upgrade legacy useState/useEffect mutation flows to React 19 useActionState, useOptimistic, and uncontrolled FormData when on React 19. Before replacing a controlled form, verify that input state survives network failure per ui-ux-review INV-7. If uncontrolled migration would drop draft persistence, retain the controlled form and use useActionState solely for submit-state tracking.
• Place Server Actions in dedicated files with 'use server' at the top (never inside 'use client' files). Validate session credentials and tenant access inside the action. Return serializable discriminated unions (ActionState { ok: boolean, error: string | null }) instead of throwing raw errors that Next.js censors in production.
• When compiler: true, do not add manual useMemo, useCallback, or React.memo. Use immutable derivations (.toSorted()) and accept ref as a standard React 19 prop.
• For high-frequency interactive controls like range sliders, separate local thumb position state from transitioned data filtering to preserve responsive input tracking.
• Use .reduce() instead of Math.max(...array) for numeric aggregations over dynamic datasets to prevent call stack size limits.

Completion criterion: Targeted components implement the rule pattern with zero orphan imports, verified security boundaries, and clean compiler derivation paths.

Step 5. Verification pass

Run build commands, test suites, and type checks to verify that the bottleneck is eliminated:

npx next typegen && npx tsc --noEmit && npm test

Completion criterion: Clean build exit code, passing test assertions, and verified elimination of the target performance defect.

Boundary isolation

Confine optimization strictly to component rendering patterns, bundle splitting, and data fetching:

• Preserve backend API route contracts, database schemas, and business validation logic.
• Never modify component visual aesthetics, design tokens, or typography in the name of performance.
• Preserve existing accessibility attributes and semantic markup; never remove aria attributes or keyboard handlers to simplify rendering.
• Preserve public exported signatures, but narrow internal 'use client' props to minimal serializable DTOs. Block raw database model leakage across the Client boundary using experimental_taintObjectReference.
• Ensure 'use client' is explicitly declared at the top of client component files.
• Type Next.js 15 params and searchParams as Promises (Promise<{ slug: string }>) and await them concurrently with cookies().
• Guard concurrent RSC reads with Promise.allSettled and an AbortController timeout signal to prevent whole-page crashes and detached orphaned queries.

Rule categories by priority

Detailed rule specifications, code examples, and bad versus good patterns are stored individually in references/rules/<prefix>-<name>.md.

Quick audit checklist

Review this table before completing React optimization tasks: