React Hooks Complete Technical Reference

Critical Production Failures and Their Causes

useState Mutation Bugs

Problem: Direct state mutation causes components to not re-render
Impact: Production checkout flow failure, revenue loss
Root Cause: React uses Object.is() reference comparison - same reference = no re-render

// BREAKS PRODUCTION - Direct mutation
const addItem = (newItem) => {
  items.push(newItem); // Same array reference
  setItems(items); // React ignores update
};

// WORKS - New reference
const addItem = (newItem) => {
  setItems([...items, newItem]); // New array reference
};

useEffect Infinite Loops

Problem: Missing/incorrect dependency arrays create infinite API calls
Impact: API server crashes, staging environment failures
Frequency: Extremely common, affects most React developers

// KILLS API SERVER
useEffect(() => {
  fetchData();
}); // No dependency array = runs every render

// CORRECT
useEffect(() => {
  fetchData();
}, []); // Empty array = runs once on mount

State Management Configuration

useState Async Update Gotcha

Issue: State updates are batched and asynchronous
Failure Mode: Expecting immediate state availability

// WRONG - Uses stale state
const increment = () => {
  setCount(count + 1);
  setCount(count + 1); // Still uses old count
};

// CORRECT - Functional updates
const increment = () => {
  setCount(prev => prev + 1);
  setCount(prev => prev + 1); // Uses updated value
};

useReducer vs useState Decision Matrix

Scenario	Use useState	Use useReducer
Simple values	✓
Form inputs	✓
5+ related state variables		✓
Complex state transitions		✓
State depends on previous state		✓

useEffect Critical Patterns

Cleanup Requirements

Critical: Always cleanup subscriptions, timers, and async operations
Consequence: Memory leaks, state updates on unmounted components

useEffect(() => {
  let cancelled = false;
  
  async function fetchData() {
    const result = await api.getData();
    if (!cancelled) { // Prevent state update if unmounted
      setData(result);
    }
  }
  
  fetchData();
  return () => { cancelled = true; }; // REQUIRED cleanup
}, []);

Dependency Array Rules

1. Empty array []: Run once on mount
2. No array: Run on every render (usually wrong)
3. [dependency]: Run when dependency changes
4. Include ALL values from component scope used inside effect

Performance Optimization Guidelines

useMemo Decision Tree

Is calculation > 50ms expensive?
├─ Yes: useMemo might help
├─ No: Skip it, overhead not worth it

Processing > 1000 items?
├─ Yes: useMemo beneficial
├─ No: Regular calculation faster

useCallback Usage Rules

Only use when:

• Function passed to React.memo wrapped component
• Function is dependency in useEffect/useMemo
• Measured performance problem exists

Don't use for:

• Every function (creates more overhead)
• Functions not passed as props
• Simple event handlers

Context Performance Warnings

Problem: Every context consumer re-renders when ANY part of context value changes
Solution: Split contexts by update frequency
Breaking Point: Frequent updates (>10 per second) with many consumers

Custom Hooks Production Patterns

Data Fetching with Request Cancellation

function useApi(url) {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);
  const cancelRef = useRef();
  
  useEffect(() => {
    // Cancel previous request
    if (cancelRef.current) cancelRef.current();
    
    let cancelled = false;
    cancelRef.current = () => { cancelled = true; };
    
    fetch(url, { signal: AbortSignal.timeout(10000) })
      .then(response => {
        if (!cancelled) setData(response);
      })
      .catch(err => {
        if (!cancelled && err.name !== 'AbortError') {
          setError(err.message);
        }
      });
    
    return () => { if (cancelRef.current) cancelRef.current(); };
  }, [url]);
  
  return { data, loading, error };
}

React 19 New Hooks

use Hook

Unique Feature: Can be called conditionally (breaks traditional hook rules)
Use Cases: Promise handling, conditional data fetching

function UserProfile({ userId, showDetails }) {
  if (!showDetails) return <div>Hidden</div>;
  
  const user = use(fetchUser(userId)); // Conditional hook call allowed
  return <div>{user.name}</div>;
}

useActionState

Purpose: Form state management with built-in pending states
Replaces: Manual form loading/error handling

useOptimistic

Purpose: Immediate UI updates while async operations run
Benefit: Better perceived performance
Use Case: Todo toggles, like buttons, form submissions

Hook Lifecycle Flow

1. Render Phase: React calls component function, hooks capture state/effects
2. Commit Phase: DOM updates happen, useLayoutEffect runs synchronously
3. Effect Phase: useEffect callbacks run asynchronously after paint

Common Debugging Scenarios

Component Not Re-rendering

Cause: Direct state mutation (90% of cases)
Solution: Always create new objects/arrays for state updates

useEffect Running Too Often

Cause: Missing dependencies or object/function dependencies changing every render
Solution: Use ESLint plugin, memoize dependencies

Performance Issues

Cause: Overuse of useMemo/useCallback on cheap operations
Solution: Profile first, optimize only measured bottlenecks

Critical Dependencies

Required Tools

• ESLint plugin for hooks: Prevents dependency array bugs
• React DevTools: Profiler tab shows re-render frequency
• AbortController: Request cancellation (10s timeout recommended)

Recommended Libraries

• React Query: Replaces manual useEffect data fetching
• Zustand: Context alternative for frequently updating state
• @testing-library/react: Hook testing utilities

Version Compatibility

React 18 vs 19

• React 18: Standard hooks, requires careful dependency management
• React 19: Adds use, useActionState, useOptimistic hooks
• Migration: React 19 fixes some useEffect edge cases but breaking changes exist

Testing Patterns

// Test hooks in isolation
import { renderHook, act } from '@testing-library/react';

test('useCounter increments', () => {
  const { result } = renderHook(() => useCounter(0));
  
  act(() => {
    result.current.increment();
  });
  
  expect(result.current.count).toBe(1);
});

Resource Requirements

Time Investment

• Learning curve: 2-4 weeks for experienced React developers
• Migration from classes: 1-2 months for large codebases
• Debugging skills: 6 months to identify common pitfalls quickly

Performance Thresholds

• UI breaks at: 1000+ spans (distributed transaction debugging impossible)
• API rate limits: useEffect infinite loops can generate 1000+ requests/second
• Context performance: >10 updates/second with >20 consumers causes lag

Common Gotchas by Experience Level

• Junior: Wrapping everything in useMemo/useCallback
• Mid-level: Incorrect dependency arrays causing infinite loops
• Senior: Overengineering simple state with useReducer

This technical reference provides the operational intelligence needed for successful React Hooks implementation while avoiding the common pitfalls that cause production failures.