react-performance

Performance Debugging Workflow

Always follow this order — measure before optimizing:

1. Reproduce — Document exact steps, browser, device, network conditions
2. Measure — Profile with React DevTools Profiler + Chrome Performance tab. Never measure development builds.
3. Identify — Form a specific hypothesis about the cause
4. Fix — Apply the minimal fix needed
5. Verify — Measure improvement under same conditions

Rule #1: Do NOT measure the development build. For production profiling, alias:

• react-dom$ → react-dom/profiling
• scheduler/tracing → scheduler/tracing-profiling

Rule #2: Simulate real user conditions (slow CPU, throttled network).

Why Components Re-render

Components re-render for exactly three reasons:

1. Its state changed
2. Its parent rendered (unless wrapped in React.memo)
3. A consumed Context value changed

Renders are either necessary or unnecessary. Any single unnecessary render is rarely a problem — it's the accumulation over time.

State Architecture (Fix Before Memoizing)

Before reaching for memoization, fix your state architecture. These are free performance wins:

Colocate State

Move state to the closest component that needs it. State at the root re-renders the entire tree.

// BAD: searchQuery in App re-renders Header, Cart, Footer
function App() {
  const [searchQuery, setSearchQuery] = useState("");
  return (
    <>
      <Header />
      <SearchBar query={searchQuery} onChange={setSearchQuery} />
      <Cart />
    </>
  );
}

// GOOD: searchQuery lives in SearchSection
function App() {
  return (
    <>
      <Header />
      <SearchSection />
      <Cart />
    </>
  );
}
function SearchSection() {
  const [searchQuery, setSearchQuery] = useState("");
  return <SearchBar query={searchQuery} onChange={setSearchQuery} />;
}

Derive, Don't Store

If a value can be computed from existing state/props, compute it — don't store it.

// BAD: synchronized state
const [items, setItems] = useState<Item[]>([]);
const [filteredItems, setFilteredItems] = useState<Item[]>([]);
// Must keep in sync — bugs + extra renders

// GOOD: derived value
const [items, setItems] = useState<Item[]>([]);
const filteredItems = items.filter((i) => i.active); // or useMemo if expensive

Lift State Intelligently

Only lift state to the lowest common ancestor that needs it — no higher.

Memoization Decision Guide

Three memoization tools, each with specific use cases:

Key rule: useMemo/useCallback are pointless without React.memo on the receiving child (or a dependency array consumer).

When NOT to Memoize

• Simple/cheap components that render fast
• Props that change on almost every render anyway
• Components without memoized children receiving the value
• Simple calculations (the comparison overhead exceeds computation cost)

React Compiler

The React Compiler is a Babel plugin that automatically applies memoization at build time. It analyzes your code and inserts useMemo/useCallback where safe.

Prerequisites: Code must follow the Rules of React — components must be pure, props/state immutable, no side effects in render.

What the Compiler Handles

• Stabilizing callback identities (replaces manual useCallback)
• Memoizing derived values (replaces manual useMemo)
• Memoizing JSX output (replaces many React.memo wrappers)

What You Still Need Manually

• React.memo: Impure components, 3rd-party library components, explicit render boundaries
• useMemo: Truly expensive computations the compiler can't prove safe, custom equality logic
• useCallback: Complex closure semantics, library APIs requiring stable function identities

Context API Performance

Context is a broadcast mechanism — every consumer re-renders when the value changes. The fix is splitting.

The Two-Context Pattern

Separate state from dispatch/actions into two contexts so components that only dispatch never re-render when state changes (full Provider example in references/context-optimization.md).

Split by Domain

Never create a "mega context" with unrelated state. Split into ThemeContext, AuthContext, UIContext, etc.

Concurrent Features

useTransition vs useDeferredValue

Neither makes anything faster — they make the UI feel faster by prioritizing urgent updates (typing) over expensive work (filtering). Code examples for both, plus Suspense and data-fetching patterns, live in references/concurrent-features.md.

Bundle Performance

Code Splitting Checklist

1. Route-based splitting — lazy() + Suspense for each route
2. Heavy component splitting — Lazy-load modals, charts, editors
3. Conditional feature splitting — Admin panels, premium features
4. Bundle analysis — Use webpack-bundle-analyzer or source-map-explorer
5. Tree shaking — Use named exports, check sideEffects in package.json

Core Web Vitals Quick Reference

React Fiber — How Rendering Works

React Fiber is a cooperatively-scheduled rendering engine using a linked-list tree structure.

• Two trees: Current (what DOM reflects) and Work-in-Progress (draft being prepared)
• Yielding: React yields to browser every ~5ms, allowing paint/input handling
• Lanes: Priority system using bitmasks — SyncLane > InputContinuousLane > DefaultLane > TransitionLane > IdleLane
• Commits are never interrupted — once render phase completes, DOM updates happen synchronously

Understanding this helps explain why useTransition works: it assigns updates to lower-priority lanes.

References

Each file is loaded on demand — read one only when the task needs that depth (progressive disclosure).

• references/profiling-and-debugging.md — the systematic measure-before-optimize workflow, the React DevTools Profiler, the Chrome Performance tab, and production-profiling build setup · read when measuring, reproducing, or diagnosing a slowdown before touching code.
• references/memoization-patterns.md — React.memo, useMemo, and useCallback in depth with custom comparators and the dependency-array rules · read when applying memoization or deciding which of the three to reach for.
• references/react-compiler.md — React Compiler setup, how it auto-memoizes, migration steps, and what still needs manual memoization · read when adopting/migrating to the React Compiler or auditing what it can't cover.
• references/context-optimization.md — the two-context (state/dispatch) Provider pattern, the mega-context anti-pattern, and domain splitting · read when a Context value re-renders too many consumers.
• references/concurrent-features.md — useTransition, useDeferredValue, and Suspense with full code and data-fetching patterns · read when making expensive updates non-blocking or wiring Suspense.
• references/bundle-and-loading.md — code splitting, lazy()/Suspense route and component splitting, lazy-loading patterns, tree shaking, and bundle analysis · read when reducing bundle size or implementing lazy loading.