React Performance Optimizer Agent

Diagnoses React rendering bottlenecks, bundle bloat, memory leaks, and Core Web Vitals regressions in production applications.

When to Use This Agent

Choose this agent when you need to:

• Profile React render cycles using concurrent features, memoization, and virtualization
• Analyze and reduce bundle sizes through code splitting and dependency replacement
• Implement Core Web Vitals monitoring specific to React's rendering and hydration pipeline

Consider alternatives when:

• Performance issues stem from backend API latency rather than frontend rendering
• You need architecture guidance for new features rather than optimizing existing ones

Quick Start

Configuration

Copy
name: react-performance-optimizer-agent
type: agent
category: web-tools

Example Invocation

Copy
claude agent:invoke react-performance-optimizer-agent "Profile Dashboard component tree for unnecessary re-renders"

Example Output

Re-render Analysis: Dashboard
==============================
EXCESSIVE RENDERS:
  1. <UserAvatar /> 47/sec (cause: parent state update)
     Fix: Wrap with React.memo
  2. <NotificationBell /> 23/sec (cause: context consumer)
     Fix: Split NotificationContext into Count + List contexts
  3. <SidebarNav /> 12/sec (cause: inline object prop)
     Fix: Extract navConfig to module-level constant

MEMORY: 342 detached DOM nodes from VirtualList unmount
  Fix: Add IntersectionObserver cleanup in useEffect
Impact: -63% render cycles, -18ms interaction latency

Core Concepts

Performance Domains

Aspect	Details
Render Optimization	React.memo, useMemo, useCallback, avoiding inline object/function props
Concurrent Features	useTransition, useDeferredValue for non-blocking UI during heavy computation
Virtualization	react-window/react-virtuoso for rendering only visible items in long lists
Bundle Analysis	Webpack treemaps, chunk splitting, and dependency audit for dead code
Memory Management	useEffect cleanup, listener deregistration, and WeakRef for caches

React Render Pipeline

+-------------------+     +-------------------+     +------------------+
|  State Change     |---->|  Reconciliation   |---->|  DOM Commit      |
|  (setState/ctx)   |     |  (VDOM diffing)   |     |  (Paint/Layout)  |
+-------------------+     +-------------------+     +------------------+
       |                         |                         |
       v                         v                         v
+-------------------+     +-------------------+     +------------------+
|  Avoid Trigger    |     |  Minimize Diff    |     |  Reduce Paint    |
|  React.memo       |     |  useMemo/keys     |     |  CSS containment |
|  Context split    |     |  Virtualization   |     |  will-change     |
+-------------------+     +-------------------+     +------------------+

Configuration

Parameter	Type	Default	Description
profiling_mode	string	"development"	Build: "development" for DevTools or "production" for real metrics
bundle_budget_kb	number	250	Max client JS budget before optimization triggers
render_threshold_ms	number	16	Max render duration (one frame at 60fps)
memory_check	boolean	true	Enable detached DOM and listener leak detection
vitals_tracking	boolean	true	Enable LCP, FID, CLS measurement and alerting

Best Practices

1. Profile Before Optimizing - Use React DevTools Profiler to record flamegraphs before adding memoization. Premature React.memo adds complexity without benefit if the component was not re-rendering excessively.

2. Split Context by Update Frequency - A single context holding fast-changing data (notification count) and stable data (user preferences) re-renders all consumers on any update. Split by frequency to insulate stable subscribers.

3. Virtualize Lists Beyond 100 Items - Hundreds of DOM nodes require layout and paint even when off-screen. Libraries like react-window render only the visible slice, reducing render time from seconds to milliseconds.

4. Replace Heavy Dependencies - Swap moment.js (67KB) for date-fns, lodash (72KB) for lodash-es or native methods. Each replacement compounds into meaningful bundle reduction.

5. Enforce Performance Budgets in CI - Add bundle size checks with bundlesize or size-limit. Failing builds when client JS exceeds thresholds prevents regressions from merging unnoticed.

Common Issues

1. Inline Props Defeat React.memo - style={{color:'red'}} creates new references every render, bypassing memoization. Extract to module-level constants or useMemo for referential stability.

2. useEffect Missing Cleanup - Listeners and observers without cleanup functions accumulate on remount. StrictMode double-mounts double the leak rate. Always return a cleanup function.

3. Code Splitting Waterfalls - Splitting every component with React.lazy creates sequential loading chains. Group related components into shared chunks and preload critical lazy chunks to parallelize fetching.