React

Targets React 19.2 and React Compiler 1.0 (babel-plugin-react-compiler), linted by eslint-plugin-react-hooks 7.1+. Read the reference matched by the API or behavior being changed. Load adjacent references only for concerns the change crosses; reuse relevant context already read.

The compiler is the optimizer

The compiler applies the equivalent of memo to every component and memoizes calculations inside components and hooks, at build time. It does this more granularly than hand-written hooks can — it memoizes after early returns, where useMemo is structurally forbidden.

The price is that the Rules of React stopped being style advice and became a build-time contract. When a component violates them, the compiler bails: it silently skips optimizing that component and moves on. The build stays green, the tests stay green, and the component is simply never optimized. Write code the compiler cannot bail on.

Two consequences that invert pre-compiler habits:

• Reflexive useMemo/useCallback on cheap values is now noise, and an incomplete dependency array is worse than no memoization at all — the compiler refuses to optimize a component whose manual memoization it cannot match.
• A rule violation costs optimization silently rather than raising an error, so the lint rules are the only thing standing between you and a quietly unoptimized app. Enable them before enabling the compiler.

Decide memoization first

Situation	Do
New value or callback consumed only by render/JSX	Write it plainly; the compiler memoizes it
Value feeds a useEffect (or another hook's) dependency array and identity must hold	Keep useMemo/useCallback — the escape hatch react.dev names by name
Value crosses to a non-compiled consumer (vanilla lib instance, addEventListener, uncompiled package)	Keep manual memoization
Manual memoization you keep for any reason	Make its deps exhaustive, or the component bails
Working memoization in existing code	Leave it — removing it changes compilation output; test before touching
Same expensive call repeated across components	Compiler memoization is per-component, never shared; hoist to a module-level cache or the data layer
Expensive work in a plain module-level util	Not memoized at all; the compiler only covers components and hooks
memo() with a custom areEqual comparator	Keep it; the compiler has no equivalent

Done when: each memoization added or changed by this task traces to a row above, and no row was satisfied by adding a hook the compiler already covers.

Branches

When you are…	Reference
Writing or reviewing any component or hook body — purity, mutation, refs, globals	references/rules-of-react.md
Removing, keeping, or debating a useMemo/useCallback/memo, or a component was skipped by the compiler	references/compiler.md
Installing or configuring the compiler, the lint preset, or adopting it incrementally	references/compiler-setup.md
Reaching for useEffect, or deriving/syncing state	references/effects.md
Shaping components, composition, props, or TypeScript types	references/components-and-types.md
Choosing where state lives, wiring context or an external store	references/state.md
Using use(), Actions, useOptimistic, <Activity>, metadata, or other React 19 APIs	references/react19-apis.md
Writing or fixing component/hook tests	references/testing.md

Apply the technical rules relevant to the changed behavior.

Tripwires

Purity — render computes from props, state, and context only. Math.random(), Date.now(), new Date(), crypto.randomUUID(), and performance.now() belong in a state initializer, an event handler, or an effect.

Mutation — props, state, hook arguments, hook return values, and any value already handed to JSX are read-only; copy before changing (setItems([...items].sort())). A value created in this render that never escapes is yours to mutate freely.

Reassignment — treat a destructured prop as read-only: rename on destructure ({ value: valueFromProps }) and derive a new const.

Refs — read and write ref.current in effects and event handlers. During render the only sanctioned touch is one-time lazy init: if (ref.current === null) ref.current = ….

Globals — module scope holds constants; per-render values live in useState/useContext and outward writes in an effect. Counters, arrays, and ad-hoc caches touched during render break Fast Refresh and forfeit compilation.

Components are static — declare components and hooks at module scope. Defining one inside another component (or returning one from a factory) makes a new type every render, resetting state and tearing down DOM.

Effects — an effect exists to synchronize with something outside React. Synchronous setState in an effect to derive or copy state is an error-level lint violation; compute during render instead.

Errors — child render errors are caught by an Error Boundary, never by try/catch around JSX.

Refs are props — forwardRef is deprecated in 19; accept ref in the props type. Likewise <Context value={…}>, not <Context.Provider>.

Escape hatch — "use no memo" is a bisection tool carrying a written reason and a removal plan, not a fix.

Related skills

tanstack for TanStack Query, Router, and Form. xstate-store for @xstate/store. shadcn for component primitives and CVA variants. tailwindcss for styling. vitest for runner configuration beyond references/testing.md.