React Foundations

Modern React development patterns for functional components, JSX, props, state, and hooks. All guidance targets current React practices — no class components or legacy lifecycle methods.

Component Purity

Components must be pure and idempotent — same inputs (props, state, context) always produce the same output. Side effects belong in event handlers or hooks like useEffect, never in the render path.

Allowed: Local mutation during rendering (creating and modifying arrays within the render function). Forbidden: Mutating external variables, DOM manipulation, or network requests during render.

JSX Rules

• Standard HTML attributes use camelCase: htmlFor, tabIndex, className
• ARIA and data attributes stay hyphen-cased: aria-label, data-testid
• Return a single root element — use Fragments (<>...</>) to avoid wrapper divs that break semantic layout
• Values passed into JSX are immutable — never mutate after passing

Props Patterns

Props are immutable snapshots for a single render. Never mutate them directly.

• Destructure in the signature: function Card({ title, children }) {}
• Default values via JS defaults: function Button({ variant = "primary" }) {} — do not use defaultProps or React.FC
• Composition via children: Pass components as children to avoid prop drilling. This pattern enables passing Server Components into Client Components.

State with useState

• Immutable updates: Use spread operator for objects/arrays — useState does not auto-merge
• Functional updates: When new state depends on previous: setCount(prev => prev + 1)
• Lazy initialization: Pass a function for expensive initial values: useState(() => computeExpensive())
• Never mutate directly: state.value = 2 does not trigger re-render — always use the setter

Rules of Hooks

Hooks must follow strict rules so React can track state between renders:

1. Top level only — never inside loops, conditions, nested functions, after early returns, or in try/catch
2. React functions only — call from functional components or custom hooks, nowhere else
3. Dependency arrays must be exhaustive — include all reactive values referenced inside the hook. Omitting dependencies causes stale closures.

Enforce with eslint-plugin-react-hooks — the rules-of-hooks and exhaustive-deps rules catch violations at build time.

useEffect — Mental Model and Rules

`useEffect` is an escape hatch to synchronize with systems outside of React — not a lifecycle method and not a way to orchestrate data flow inside the component tree.

The Key Question: Effect or Event Handler?

Ask why the code needs to run:

useEffect Anti-Patterns — Critical Rules

1. Never use useEffect to compute derived state. If you can calculate it from existing props/state, do it during render: const fullName = firstName + ' ' + lastName; — no effect needed.
2. Always return a cleanup function when subscribing, adding event listeners, or starting timers. Failure causes memory leaks and stale handlers.
3. Never pass an async function directly to useEffect. Define an inner async function and call it.
4. Race conditions in data fetching: Use AbortController + cleanup to cancel stale requests. Every fetch inside useEffect needs cancellation handling.
5. Never chain Effects to update state based on other state — this causes cascading re-renders and brittle code.
6. Object/function dependencies: Pass primitive values (e.g., user.id) or memoize with useCallback/useMemo to prevent unnecessary re-runs.

// CORRECT: cleanup + AbortController
useEffect(() => {
  const controller = new AbortController();
  async function load() {
    const data = await fetchUser(id, { signal: controller.signal });
    setUser(data);
  }
  load();
  return () => controller.abort();
}, [id]);

// WRONG: async directly as effect, no cleanup
useEffect(async () => { setUser(await fetchUser(id)); }, [id]);

See references/detailed-patterns.md for the complete list of 15 useEffect mistakes with fixes.

Derived State — Core Rule

If a value can be computed from existing props or state, it is NOT state. Never store it in useState and never sync it with useEffect.

// BAD: double render, brittle synchronization
const [fullName, setFullName] = useState('');
useEffect(() => setFullName(`${firstName} ${lastName}`), [firstName, lastName]);

// GOOD: calculated during render
const fullName = `${firstName} ${lastName}`;

Use useMemo only if the calculation is provably expensive.

Core Hooks Quick Reference

Custom Hooks

Extract reusable stateful logic into functions starting with use. Each call gets independent state.

• Keep hooks focused on concrete use cases: useOnlineStatus(), useChatRoom(options)
• Anti-pattern: Abstract lifecycle wrappers like useMount(fn) — these bypass linting and break the React paradigm
• Return tuples with as const for correct TypeScript inference

Additional Resources

Reference Files

• `references/detailed-patterns.md` — Complete code examples for all hook patterns, prop patterns, JSX edge cases, and common anti-patterns with fixes