Hook design and dependencies

Design the hook’s surface first: clear inputs, a predictable return shape. Before any effect, decide what goes in and what comes out — and keep the shape of the return stable across renders so consumers can destructure it once. Return a tuple when order is obvious and small ([value, setValue]), an object when there are several named pieces (so callers pick what they need without positional guessing).

// object return: named, extensible, order-independent
function useToggle(initial = false) {
  const [on, setOn] = useState(initial);
  const toggle = useCallback(() => setOn((v) => !v), []);
  return { on, toggle, setOn }; // same keys every render → stable shape
}

A predictable shape is part of the contract. If the hook sometimes returns undefined and sometimes an object, every consumer has to guard. Pick a shape and hold it for every render, including the first.

The dependency array is a claim: “these are the values this effect reads.” A lying dep array is the bug. exhaustive-deps isn’t nagging — it’s checking your claim against reality. If the effect closes over delay but you write [], you’ve told React “this effect reads nothing,” so it never re-runs when delay changes, and the interval keeps firing on the original delay forever. That’s a stale closure: the effect captured render-zero’s values and was never told to refresh.

// LYING dep array: effect reads `delay` but claims to read nothing
useEffect(() => {
  const id = setInterval(tick, delay); // captures the FIRST delay
  return () => clearInterval(id);
}, []); // ❌ omits `delay` → never updates when delay changes

The fix is never “silence the lint rule.” It’s either list the dependency honestly (and accept the re-subscribe), or restructure so the effect genuinely doesn’t depend on it — which is exactly what a ref buys you in Step 4.

Cleanup is the other half of the contract: every subscription you set up, you tear down. An effect that adds a listener, opens an interval, or subscribes to a store must return a function that undoes it. Skip it and you leak — duplicate listeners stack up across re-renders and unmounts, intervals keep ticking after the component is gone, and you get “setState on an unmounted component” warnings or, worse, silent double-fires.

function useEventListener(type: string, handler: (e: Event) => void) {
  useEffect(() => {
    window.addEventListener(type, handler);
    return () => window.removeEventListener(type, handler); // ← the contract
  }, [type, handler]); // re-subscribes if either changes
}

There’s a hidden trap here: handler is in the deps, so an inline handler (new identity every render) makes this re-subscribe on every render. That’s correct but wasteful — and it’s the exact pressure that justifies the ref pattern next.

Use a ref to read the latest callback without re-subscribing — the senior fix for the stale-closure / churn tension. You want two things that fight each other: the effect should always call the latest handler (no stale closure), but it shouldn’t tear down and re-create the subscription every render. A ref resolves it: store the newest handler in a ref (updated each render), subscribe once with a stable wrapper that reads ref.current at call time.

function useInterval(callback: () => void, delay: number | null) {
  const savedCallback = useRef(callback);
  useEffect(() => { savedCallback.current = callback; }); // always latest, no churn

  useEffect(() => {
    if (delay === null) return;                       // null = paused
    const id = setInterval(() => savedCallback.current(), delay);
    return () => clearInterval(id);                    // cleanup matches setup
  }, [delay]); // ✅ honest: only delay actually drives re-subscribe
}

Now delay is the only thing that re-subscribes, the callback is never stale, and the dep array tells the truth. That’s the whole pattern: a ref absorbs the “latest value” need so the dependency array can stay both honest and minimal.