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/useCallbackon 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
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
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.
