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