React hooks discipline

Render purity is the whole game

A component render must be a pure function of props + state + context. Anything else belongs in effects or event handlers.

• Never mutate refs during render (read-only in render; write in effects/handlers).
• Never call setState unconditionally in render or in the body of another component.
• Derived data → useMemo or plain computation, not a second useState kept in sync:

// ❌ duplicated state to keep in sync
const [fullName, setFullName] = useState('')
useEffect(() => setFullName(`${first} ${last}`), [first, last])

// ✅ derived
const fullName = `${first} ${last}`

Dependency arrays: be exhaustive, then be honest

1. Enable eslint-plugin-react-hooks exhaustive-deps and treat warnings as errors.
2. If you must omit a dependency, write why in a comment and prefer restructuring:

// ❌ lie: latest always wins, silently breaks subscription
useEffect(() => {
  const id = setInterval(() => poll(url), 5_000)
  return () => clearInterval(id)
}, []) // url "won't change" — until it does

// ✅ restructure: keep it fresh via ref, or include it
const urlRef = useRef(url)
useEffect(() => { urlRef.current = url }, [url])
useEffect(() => {
  const id = setInterval(() => poll(urlRef.current), 5_000)
  return () => clearInterval(id)
}, [])

3. Objects/arrays/functions as deps re-fire every render — stabilize at the source (useMemo/useCallback at the producer, or hoist constants out).

Custom hooks: same rules as components

• Every custom hook returns a stable shape (tuple or object — pick per codebase and stick to it).
• Effects in custom hooks still clean up. If it subscribes, it unsubscribes — no exceptions.
• One behavior per hook. useUserWithPostsAndComments is three hooks wearing a trench coat.

The patterns that prevent 90% of bugs

• Latest-value ref for subscriptions/intervals that shouldn't re-arm (above).
• Abort on unmount for fetches:

useEffect(() => {
  const ac = new AbortController()
  fetch(url, { signal: ac.signal })
    .then(setData)
    .catch((e) => e.name !== 'AbortError' && setError(e))
  return () => ac.abort()
}, [url])

• Event → effect split: if logic runs "when the user clicks", it lives in the handler, not in an effect watching a state flag.

Anti-patterns

• Conditional hooks or hooks in loops/conditions (rule of hooks — non-negotiable).
• useEffect chains mirroring imperative flows (a → b → c). Model state, not steps.
• Context value recreated every render without memoization — memoize the value object or split contexts.
• Storing functions in state; store data, derive behavior.

Definition of done (agent checklist)

• exhaustive-deps clean, deviations documented with reason
• Every effect with a subscription/timer/fetch has cleanup
• No state that is derivable from props/state
• Keys on lists are stable ids
• No ref writes during render