React Performance

Comprehensive React performance guidance covering measurement, rendering optimization, bundle size, Core Web Vitals, and Server Component patterns. Verified against React docs and Web Vitals specifications.

First principle: Measure before you optimize. This skill teaches you to find problems before fixing them.

Contents

• Architecture Overview
• Quick Reference
• Decision Matrix: Which Optimization?
• Choose a proportional fix
• Anti-Patterns Checklist

Architecture Overview

[Diagnose]
    ├── React DevTools Profiler (component render times)
    ├── Chrome Performance Panel (main thread activity)
    ├── web-vitals library (LCP, INP, CLS in production)
    └── Bundle analyzer (what's in the bundle)
              ↓
[Identify Root Cause]
    ├── Unnecessary re-renders? → Memoization / state colocation
    ├── Slow initial load? → Code splitting / Server Components
    ├── Janky interactions? → useTransition / useDeferredValue
    ├── Layout shifts? → Image/font optimization
    └── Large bundle? → Dynamic imports / tree shaking
              ↓
[Fix — Least Invasive First]
    ├── 1. Restructure components (children pattern, local state)
    ├── 2. Consider incremental Compiler adoption if supported and justified
    ├── 3. Use concurrent features (transitions, deferred values)
    ├── 4. Move work to Server Components
    ├── 5. Code split heavy dependencies
    └── 6. Manual memo/useMemo/useCallback (last resort)

Before prescribing an API, inspect the app's installed React/Next versions, bundler and Compiler configuration. Preserve the project's supported setup; an optimization task is not automatic authorization to enable a compiler or change frameworks. Source checks are scoped in SOURCES.md.

Quick Reference

Decision Matrix: Which Optimization?

"My page loads slowly"

"My page feels janky/unresponsive"

"Layout is jumping around"

"Should I use memo/useMemo/useCallback?"

Inspect whether the affected component is actually compiled. Prefer measuring and fixing state placement or repeated work first. Existing memo/useMemo/useCallback can remain; do not remove them in bulk when enabling Compiler. If the compiler covers new code, manual memoization is often unnecessary, but it can still be useful for a measured case or an external identity contract. A stable callback can matter to an Effect or subscription even when a child is not wrapped in memo.

Choose a proportional fix

Keep code correct, identify the measured bottleneck, and choose the smallest effective change: component structure, memoization, deferred rendering, bundle splitting or server work where the framework supports it. Compiler adoption is a separate, incremental project choice with behavior/performance checks, not an official universal ordering of optimizations. Transitions schedule rendering; they do not split an expensive synchronous function into yielding work.

Anti-Patterns Checklist

When reviewing code, watch for these performance killers:

• Effect chains — useEffect that sets state triggering another useEffect (derive during render instead)
• Inline object/function props to memo()-wrapped children (defeats memoization)
• State too high — input state at page level re-rendering entire tree
• useEffect for derived state — setFiltered(items.filter(...)) in effect (use useMemo or calculate during render)
• Missing key prop — or using array index as key for dynamic lists
• Context monolith — one Provider with user + theme + cart + notifications
• Client Component boundary too high — 'use client' at layout/page level instead of leaf components
• Heavy imports in client bundle — syntax highlighters, markdown parsers, date libraries not code-split
• Images without dimensions — causes CLS
• onPaste={e => e.preventDefault()} on password fields — blocks password managers (also an a11y violation)
• Manual memo/useMemo/useCallback without measuring first — adds complexity for no proven benefit
• Per-asset state or store hook under thousands of siblings. The cost is the walk from the root. Subscribe in an effect and write the DOM. See rendering.md.
• new ExpensiveThing() in useRef initializer — runs every render (use lazy init pattern)
• useState(expensive()). The call runs on every render. Pass () => expensive().
• A component declared inside another component. It remounts on every parent render. Declare it at module level.
• App-wide setup in a mount Effect. It runs twice in development. Use a module-level flag or module top-level code.
• State set after await inside startTransition. It is not a transition. Wrap it in another startTransition.