useReducer in React — Why It Exists and How to Use It Simply

...state, items: updatedItems, total: state.total - itemToRemove.price, }; }

case 'APPLY_DISCOUNT': {
  const discount = action.payload;
  if (discount < 0 || discount > 100) {
    return { ...state, error: 'Invalid discount percentage' };
  }
  const discountedTotal = state.total * (1 - discount / 100);
  return {
    ...state,
    total: discountedTotal,
    error: null,
  };
}

case 'SUBMIT_ORDER': {
  if (state.items.length === 0) {
    return { ...state, error: 'Cannot submit empty order' };
  }
  return { ...state, status: 'processing', error: null };
}

case 'RESET_ORDER':
  return {
    items: [],
    total: 0,
    status: 'pending',
    error: null,
  };

default:
  return state;

} }

// 4. Component Implementation const initialState: OrderState = { items: [], total: 0, status: 'pending', error: null, };

export function OrderDashboard() { const [order, dispatch] = useReducer(orderReducer, initialState);

const handleAddItem = () => { dispatch({ type: 'ADD_ITEM', payload: { id: 'item-1', name: 'Widget A', price: 29.99 }, }); };

const handleSubmit = () => { dispatch({ type: 'SUBMIT_ORDER' }); };

return ( <div> <h2>Order Status: {order.status}</h2> <p>Total: ${order.total.toFixed(2)}</p> {order.error && <p className="error">{order.error}</p>}

  <button onClick={handleAddItem}>Add Widget A</button>
  <button onClick={handleSubmit} disabled={order.status !== 'pending'}>
    Submit Order
  </button>
</div>

); }

#### Architecture Decisions

*   **Pure Reducer Function:** The reducer contains no side effects. It computes the next state based solely on the current state and action. This ensures predictability and enables unit testing without rendering the component.
*   **Action Payloads:** Actions carry only the data necessary for the transition. This decouples the component from the logic, allowing the reducer to handle calculations (e.g., updating `total` when an item is added).
*   **Default Case:** The reducer returns the current state for unknown actions, preventing crashes and ensuring stability.
*   **TypeScript Interfaces:** Strict typing for `OrderState` and `OrderAction` catches errors at compile time, ensuring actions match expected payloads and state shapes remain consistent.

### Pitfall Guide

Even with a robust pattern, developers often encounter specific issues when implementing `useReducer`. The following pitfalls and fixes are derived from production experience.

1.  **Direct State Mutation**
    *   *Explanation:* Modifying the state object directly (e.g., `state.total += 10`) breaks React's change detection. React relies on reference equality to trigger re-renders.
    *   *Fix:* Always return a new object. Use spread syntax (`{ ...state, total: state.total + 10 }`) or immutable update libraries.

2.  **Side Effects in Reducer**
    *   *Explanation:* Placing API calls, timers, or DOM manipulation inside the reducer causes unpredictable behavior. Reducers must be pure functions.
    *   *Fix:* Move side effects to event handlers or `useEffect` hooks. The reducer should only update state based on inputs.

3.  **Magic String Action Types**
    *   *Explanation:* Using raw strings for action types (e.g., `'add_item'`) increases the risk of typos, which can silently fail or cause bugs.
    *   *Fix:* Define action types as constants or use TypeScript string literals. This enables autocomplete and compile-time validation.

4.  **Over-Engineering Simple State**
    *   *Explanation:* Using `useReducer` for a simple boolean toggle or single value adds unnecessary boilerplate and complexity.
    *   *Fix:* Reserve `useReducer` for complex state with multiple update paths or interdependent fields. Use `useState` for simple, isolated values.

5.  **Payload Structure Inconsistency**
    *   *Explanation:* Varying payload structures across actions can lead to runtime errors when the reducer expects specific data.
    *   *Fix:* Define strict interfaces for each action type. Ensure payloads are validated before dispatching.

6.  **Reducer Bloat**
    *   *Explanation:* As logic grows, the reducer function can become unwieldy, reducing readability and maintainability.
    *   *Fix:* Extract complex calculations into helper functions. Consider splitting the reducer into smaller, focused reducers if the state becomes too large.

7.  **Neglecting Error Handling**
    *   *Explanation:* Failing to handle invalid actions or payloads can leave the state in an undefined condition.
    *   *Fix:* Implement validation within the reducer and update an `error` field in the state when invalid data is detected.

### Production Bundle

#### Action Checklist

- [ ] **Define State Interface:** Create a TypeScript interface for the state object to ensure type safety.
- [ ] **Define Action Types:** Establish a union type for actions with strict payload definitions.
- [ ] **Implement Pure Reducer:** Write the reducer function with no side effects, covering all action cases.
- [ ] **Initialize Hook:** Connect the reducer to the component using `useReducer(reducer, initialState)`.
- [ ] **Dispatch Actions:** Replace direct state updates with `dispatch` calls using defined action types.
- [ ] **Write Unit Tests:** Test the reducer function in isolation with various actions and state inputs.
- [ ] **Review Performance:** Ensure the reducer returns new references only when state actually changes.

#### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
| :--- | :--- | :--- | :--- |
| **Simple Toggle** | `useState` | Minimal boilerplate; direct control | Low |
| **Form with Validation** | `useReducer` | Coordinated updates; atomic transitions | Medium |
| **Multi-step Wizard** | `useReducer` | State machine pattern; clear transitions | High |
| **Interdependent Fields** | `useReducer` | Prevents data drift; ensures consistency | Medium |
| **Isolated Value** | `useState` | Simpler implementation; less overhead | Low |

#### Configuration Template

The following template provides a production-ready setup for `useReducer` with TypeScript.

```typescript
import { useReducer, Reducer } from 'react';

// State Interface
interface MyState {
  // Define state properties
  value: number;
  status: 'idle' | 'loading' | 'success' | 'error';
}

// Action Types
type MyAction =
  | { type: 'INCREMENT' }
  | { type: 'DECREMENT' }
  | { type: 'SET_VALUE'; payload: number }
  | { type: 'RESET' };

// Reducer Function
const myReducer: Reducer<MyState, MyAction> = (state, action) => {
  switch (action.type) {
    case 'INCREMENT':
      return { ...state, value: state.value + 1 };
    case 'DECREMENT':
      return { ...state, value: state.value - 1 };
    case 'SET_VALUE':
      return { ...state, value: action.payload };
    case 'RESET':
      return { value: 0, status: 'idle' };
    default:
      return state;
  }
};

// Initial State
const initialState: MyState = {
  value: 0,
  status: 'idle',
};

// Custom Hook
export function useMyState() {
  const [state, dispatch] = useReducer(myReducer, initialState);
  return { state, dispatch };
}

Quick Start Guide

1. Define State Shape: Create an interface for your state object.
2. Write Reducer: Implement a pure function handling all state transitions.
3. Initialize Hook: Call useReducer(reducer, initialState) in your component.
4. Dispatch Actions: Use dispatch to trigger state changes via defined actions.
5. Test Reducer: Verify reducer logic with unit tests for each action type.