FORBIDDEN: Truncating code or writing placeholders such as "// ... existing code ..." or "# rest unchanged". Every edit is complete and applies as written. FORBIDDEN: Reporting a check as passed without showing the command and its output. REQUIRED: Reason through the rules below before the first edit; when two rules conflict, the one stated first wins.

• Never silence the lint rule to stop a loop. It converts a visible re-render problem into an invisible stale-data problem.

---

#Purpose

Rules for using and writing hooks. Hooks are positional: React identifies them by call order, not by name. Everything in the Rules of Hooks follows from that one implementation detail.

Component-level state modelling is Frontend/react.

---

#The rules, and why they exist

tsx
// Broken — the hook order changes between renders, so React associates
// state with the wrong hook and the component corrupts silently.
if (isLoggedIn) { const [name, setName] = useState(""); }

// Correct — unconditional call, conditional value
const [name, setName] = useState("");

• Call hooks at the top level only. Never inside a condition, loop, nested function, or after an early return.
• Call them only from components or other hooks.
• Enable eslint-plugin-react-hooks and treat both rules-of-hooks and exhaustive-deps as errors. A disabled exhaustive-deps warning is a stale closure waiting to happen.

An early return before a hook is the most common accidental violation — it makes the hook count differ between renders.

---

#Dependencies are not a suggestion

tsx
// Stale closure: `query` is captured from the first render forever
useEffect(() => { search(query); }, []);

// Correct
useEffect(() => { search(query); }, [query]);

If the exhaustive list causes a loop, the fix is upstream, not a shortened array:

tsx
// Depend on the field, not the object identity
useEffect(() => { track(user.id); }, [user.id]);

Never silence the lint rule to stop a loop. It converts a visible re-render problem into an invisible stale-data problem.

---

#The right hook for the job

useSyncExternalStore is the one people miss. Reading localStorage, matchMedia, navigator.onLine or an external store with useState + useEffect produces a hydration mismatch and a flash of wrong content:

tsx
const isOnline = useSyncExternalStore(
  (cb) => { addEventListener("online", cb); addEventListener("offline", cb);
            return () => { removeEventListener("online", cb); removeEventListener("offline", cb); }; },
  () => navigator.onLine,        // client snapshot
  () => true                     // server snapshot — must be deterministic
);

A ref changing does not re-render. If the UI must reflect a value, it is state, not a ref.

---

#Effects need cleanup

tsx
useEffect(() => {
  const controller = new AbortController();
  fetch(url, { signal: controller.signal })
    .then((r) => r.json())
    .then(setData)
    .catch((e) => { if (e.name !== "AbortError") setError(e); });
  return () => controller.abort();        // cancels on unmount AND on url change
}, [url]);

Without the cleanup, two rapid changes to url can resolve out of order and the stale response wins — the classic React data race.

Every subscription, timer, listener and observer must be torn down. Strict Mode mounts, unmounts and remounts each component in development specifically to expose a missing cleanup: if that breaks your component, it is already broken.

For data fetching, prefer a library (@tanstack/react-query, SWR) or a framework loader. They handle caching, deduplication, retries and races — all of which you would otherwise reimplement per component.

---

#Custom hooks

Extract a custom hook when stateful logic is reused. Extract a plain function when the logic has no state — a function is easier to test and to reason about.

tsx
// Named for what it does, returns a stable shape, cleans up after itself
export function useDebouncedValue<T>(value: T, delayMs = 300): T {
  const [debounced, setDebounced] = useState(value);
  useEffect(() => {
    const id = setTimeout(() => setDebounced(value), delayMs);
    return () => clearTimeout(id);
  }, [value, delayMs]);
  return debounced;
}

• Name it useX — the lint rules depend on that prefix to apply hook rules.
• Return a consistent shape: a tuple for two values, an object for more.
• Do not accept props wholesale; take the specific values needed.
• A custom hook containing no hooks should be a plain function.
• Test with renderHook from @testing-library/react.

---

#Anti-patterns

---

#Checklist

• Hooks are called unconditionally at the top level of every component
• No hook follows an early return
• eslint-plugin-react-hooks runs with both rules set to error
• No exhaustive-deps suppression exists without a written justification
• Dependency arrays are complete; object identity is not depended on
• Every effect returns a cleanup for its subscriptions, timers and requests
• Data fetching aborts or ignores stale responses
• Components survive Strict Mode double-invocation
• External stores are read with useSyncExternalStore
• Refs hold only values that must not trigger a render
• Related state uses useReducer rather than many booleans
• Memoisation is applied only where profiling justified it
• Custom hooks are prefixed use and return a consistent shape
• Stateless logic is a plain function, not a hook
• Custom hooks are tested with renderHook