Files
skills/public/frontend-react-state-management.md

19 KiB

name, description
name description
frontend-react-state-management Choosing state management solution

React State Management

Scope: Context, Zustand, Jotai, Redux Toolkit, when to use each, state patterns Lines: ~300 Last Updated: 2025-10-18

When to Use This Skill

Activate this skill when:

  • Choosing state management solution
  • Managing global application state
  • Sharing state across components
  • Optimizing state updates and re-renders
  • Migrating between state libraries
  • Debugging state management issues

Core Concepts

State Types

Local State - Component-specific

const [count, setCount] = useState(0);

Shared State - Multiple components

const theme = useContext(ThemeContext);

Global State - Application-wide

const user = useStore(state => state.user);

Server State - Data from API

const { data: posts } = useSWR('/api/posts');

When to Use Each Solution

Decision Tree

State needed by single component? → useState
  ↓
State needed by 2-3 nearby components? → Lift state up or useContext
  ↓
State needed across app (5+ components)? → Zustand or Jotai
  ↓
Complex state logic (reducers, middleware)? → Redux Toolkit
  ↓
Server data (API, caching, revalidation)? → SWR or React Query

Comparison Matrix

Library Complexity Bundle Size DevTools Best For
Context Low 0kb (built-in) No Small apps, theming
Zustand Low 1.2kb Yes Most apps, simple global state
Jotai Medium 3kb Yes Atomic state, derived values
Redux Toolkit High 8kb Excellent Large apps, complex logic

React Context

Basic Context Pattern

// contexts/ThemeContext.tsx
import { createContext, useContext, useState } from 'react';

type Theme = 'light' | 'dark';

const ThemeContext = createContext<{
  theme: Theme;
  setTheme: (theme: Theme) => void;
} | null>(null);

export function ThemeProvider({ children }: { children: React.ReactNode }) {
  const [theme, setTheme] = useState<Theme>('light');

  return (
    <ThemeContext.Provider value={{ theme, setTheme }}>
      {children}
    </ThemeContext.Provider>
  );
}

export function useTheme() {
  const context = useContext(ThemeContext);
  if (!context) throw new Error('useTheme must be used within ThemeProvider');
  return context;
}

// Usage
function App() {
  return (
    <ThemeProvider>
      <Header />
      <Main />
    </ThemeProvider>
  );
}

function Header() {
  const { theme, setTheme } = useTheme();
  return (
    <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
      Toggle: {theme}
    </button>
  );
}

Context Performance Optimization

// Split context to prevent unnecessary re-renders
const UserContext = createContext<User | null>(null);
const UserActionsContext = createContext<{
  login: (email: string, password: string) => void;
  logout: () => void;
} | null>(null);

function UserProvider({ children }: { children: React.ReactNode }) {
  const [user, setUser] = useState<User | null>(null);

  // Memoize actions to prevent re-renders
  const actions = useMemo(() => ({
    login: async (email: string, password: string) => {
      const user = await loginAPI(email, password);
      setUser(user);
    },
    logout: () => setUser(null),
  }), []);

  return (
    <UserContext.Provider value={user}>
      <UserActionsContext.Provider value={actions}>
        {children}
      </UserActionsContext.Provider>
    </UserContext.Provider>
  );
}

// Components only re-render when user changes (not actions)
function UserProfile() {
  const user = useContext(UserContext);
  return <div>{user?.name}</div>;
}

// Components using actions don't re-render when user changes
function LogoutButton() {
  const { logout } = useContext(UserActionsContext)!;
  return <button onClick={logout}>Logout</button>;
}

When to use Context:

  • Simple state (theme, locale, auth user)
  • 2-5 consumers
  • Infrequent updates
  • Small apps

When NOT to use Context:

  • Frequent updates (causes re-renders)
  • Many consumers (performance issues)
  • Complex state logic

Zustand

Basic Store

// stores/useStore.ts
import { create } from 'zustand';

interface Todo {
  id: string;
  title: string;
  completed: boolean;
}

interface TodoStore {
  todos: Todo[];
  addTodo: (title: string) => void;
  toggleTodo: (id: string) => void;
  deleteTodo: (id: string) => void;
}

export const useTodoStore = create<TodoStore>((set) => ({
  todos: [],

  addTodo: (title) =>
    set((state) => ({
      todos: [...state.todos, { id: crypto.randomUUID(), title, completed: false }],
    })),

  toggleTodo: (id) =>
    set((state) => ({
      todos: state.todos.map((todo) =>
        todo.id === id ? { ...todo, completed: !todo.completed } : todo
      ),
    })),

  deleteTodo: (id) =>
    set((state) => ({
      todos: state.todos.filter((todo) => todo.id !== id),
    })),
}));

// Usage
function TodoList() {
  const todos = useTodoStore((state) => state.todos);
  const toggleTodo = useTodoStore((state) => state.toggleTodo);

  return (
    <div>
      {todos.map((todo) => (
        <div key={todo.id} onClick={() => toggleTodo(todo.id)}>
          {todo.title} - {todo.completed ? '✓' : '○'}
        </div>
      ))}
    </div>
  );
}

function AddTodo() {
  const addTodo = useTodoStore((state) => state.addTodo);

  return (
    <button onClick={() => addTodo('New Todo')}>
      Add Todo
    </button>
  );
}

Selector optimization - Component only re-renders when selected value changes:

// ❌ Re-renders on any store change
const store = useTodoStore();

// ✅ Only re-renders when todos change
const todos = useTodoStore((state) => state.todos);

Zustand with Immer (Immutability)

import { create } from 'zustand';
import { immer } from 'zustand/middleware/immer';

interface Store {
  nested: {
    deeply: {
      value: number;
    };
  };
  increment: () => void;
}

const useStore = create<Store>()(
  immer((set) => ({
    nested: { deeply: { value: 0 } },

    // Immer allows "mutation" syntax
    increment: () =>
      set((state) => {
        state.nested.deeply.value += 1;
      }),
  }))
);

Zustand with Persistence

import { create } from 'zustand';
import { persist } from 'zustand/middleware';

interface AuthStore {
  user: User | null;
  login: (user: User) => void;
  logout: () => void;
}

export const useAuthStore = create<AuthStore>()(
  persist(
    (set) => ({
      user: null,
      login: (user) => set({ user }),
      logout: () => set({ user: null }),
    }),
    {
      name: 'auth-storage', // localStorage key
    }
  )
);

When to use Zustand:

  • Most applications
  • Simple global state
  • Good performance (fine-grained subscriptions)
  • Minimal boilerplate

Jotai

Atoms (Atomic State)

// stores/atoms.ts
import { atom } from 'jotai';

// Primitive atoms
export const countAtom = atom(0);
export const userAtom = atom<User | null>(null);

// Derived atoms (computed)
export const doubleCountAtom = atom((get) => get(countAtom) * 2);

// Writable derived atoms
export const incrementCountAtom = atom(
  (get) => get(countAtom),
  (get, set) => set(countAtom, get(countAtom) + 1)
);

// Async atoms
export const postsAtom = atom(async () => {
  const res = await fetch('/api/posts');
  return res.json();
});

// Usage
function Counter() {
  const [count, setCount] = useAtom(countAtom);
  const doubleCount = useAtomValue(doubleCountAtom);

  return (
    <div>
      <p>Count: {count}</p>
      <p>Double: {doubleCount}</p>
      <button onClick={() => setCount(count + 1)}>Increment</button>
    </div>
  );
}

Atom Families (Dynamic Atoms)

import { atomFamily } from 'jotai/utils';

// Create atoms dynamically by ID
const todoAtomFamily = atomFamily((id: string) =>
  atom<Todo>({ id, title: '', completed: false })
);

function TodoItem({ id }: { id: string }) {
  const [todo, setTodo] = useAtom(todoAtomFamily(id));

  return (
    <div>
      <input
        value={todo.title}
        onChange={(e) => setTodo({ ...todo, title: e.target.value })}
      />
    </div>
  );
}

Jotai with Storage

import { atomWithStorage } from 'jotai/utils';

export const themeAtom = atomWithStorage<'light' | 'dark'>('theme', 'light');

When to use Jotai:

  • Bottom-up state (compose small pieces)
  • Derived/computed state
  • Atomic updates (fine-grained reactivity)
  • TypeScript-first

Redux Toolkit

Store Setup

// store/store.ts
import { configureStore } from '@reduxjs/toolkit';
import todosReducer from './todosSlice';
import userReducer from './userSlice';

export const store = configureStore({
  reducer: {
    todos: todosReducer,
    user: userReducer,
  },
});

export type RootState = ReturnType<typeof store.getState>;
export type AppDispatch = typeof store.dispatch;

Slice Definition

// store/todosSlice.ts
import { createSlice, PayloadAction } from '@reduxjs/toolkit';

interface Todo {
  id: string;
  title: string;
  completed: boolean;
}

interface TodosState {
  items: Todo[];
  loading: boolean;
}

const initialState: TodosState = {
  items: [],
  loading: false,
};

const todosSlice = createSlice({
  name: 'todos',
  initialState,
  reducers: {
    addTodo: (state, action: PayloadAction<string>) => {
      state.items.push({
        id: crypto.randomUUID(),
        title: action.payload,
        completed: false,
      });
    },
    toggleTodo: (state, action: PayloadAction<string>) => {
      const todo = state.items.find((t) => t.id === action.payload);
      if (todo) todo.completed = !todo.completed;
    },
    deleteTodo: (state, action: PayloadAction<string>) => {
      state.items = state.items.filter((t) => t.id !== action.payload);
    },
  },
});

export const { addTodo, toggleTodo, deleteTodo } = todosSlice.actions;
export default todosSlice.reducer;

Async Thunks

// store/userSlice.ts
import { createSlice, createAsyncThunk } from '@reduxjs/toolkit';

export const fetchUser = createAsyncThunk('user/fetch', async (userId: string) => {
  const res = await fetch(`/api/users/${userId}`);
  return res.json();
});

interface UserState {
  user: User | null;
  loading: boolean;
  error: string | null;
}

const userSlice = createSlice({
  name: 'user',
  initialState: { user: null, loading: false, error: null } as UserState,
  reducers: {},
  extraReducers: (builder) => {
    builder
      .addCase(fetchUser.pending, (state) => {
        state.loading = true;
        state.error = null;
      })
      .addCase(fetchUser.fulfilled, (state, action) => {
        state.loading = false;
        state.user = action.payload;
      })
      .addCase(fetchUser.rejected, (state, action) => {
        state.loading = false;
        state.error = action.error.message || 'Failed to fetch user';
      });
  },
});

export default userSlice.reducer;

Hooks

// hooks/redux.ts
import { TypedUseSelectorHook, useDispatch, useSelector } from 'react-redux';
import type { RootState, AppDispatch } from '../store/store';

export const useAppDispatch = () => useDispatch<AppDispatch>();
export const useAppSelector: TypedUseSelectorHook<RootState> = useSelector;

// Usage
function TodoList() {
  const todos = useAppSelector((state) => state.todos.items);
  const dispatch = useAppDispatch();

  return (
    <div>
      {todos.map((todo) => (
        <div key={todo.id} onClick={() => dispatch(toggleTodo(todo.id))}>
          {todo.title}
        </div>
      ))}
      <button onClick={() => dispatch(addTodo('New Todo'))}>Add</button>
    </div>
  );
}

When to use Redux Toolkit:

  • Large, complex applications
  • Time-travel debugging needed
  • Team familiar with Redux
  • Extensive middleware needed
  • Strict state management patterns

State Patterns

Optimistic Updates

// Zustand
const useStore = create<Store>((set) => ({
  todos: [],

  toggleTodo: async (id: string) => {
    // Optimistic update
    set((state) => ({
      todos: state.todos.map((todo) =>
        todo.id === id ? { ...todo, completed: !todo.completed } : todo
      ),
    }));

    try {
      await fetch(`/api/todos/${id}/toggle`, { method: 'POST' });
    } catch (error) {
      // Revert on error
      set((state) => ({
        todos: state.todos.map((todo) =>
          todo.id === id ? { ...todo, completed: !todo.completed } : todo
        ),
      }));
    }
  },
}));

Loading States

interface Store {
  data: Data[];
  loading: boolean;
  error: string | null;
  fetch: () => Promise<void>;
}

const useStore = create<Store>((set) => ({
  data: [],
  loading: false,
  error: null,

  fetch: async () => {
    set({ loading: true, error: null });
    try {
      const res = await fetch('/api/data');
      const data = await res.json();
      set({ data, loading: false });
    } catch (error) {
      set({ error: error.message, loading: false });
    }
  },
}));

Derived State

// Jotai - automatic memoization
const todosAtom = atom<Todo[]>([]);
const completedTodosAtom = atom((get) =>
  get(todosAtom).filter((todo) => todo.completed)
);
const activeTodosAtom = atom((get) =>
  get(todosAtom).filter((todo) => !todo.completed)
);
const statsAtom = atom((get) => {
  const todos = get(todosAtom);
  return {
    total: todos.length,
    completed: get(completedTodosAtom).length,
    active: get(activeTodosAtom).length,
  };
});

// Zustand - manual memoization
const useStore = create<Store>((set) => ({
  todos: [],
  get completedTodos() {
    return this.todos.filter((todo) => todo.completed);
  },
}));

Migration Patterns

Context → Zustand

// Before (Context)
const TodoContext = createContext<{
  todos: Todo[];
  addTodo: (title: string) => void;
} | null>(null);

function TodoProvider({ children }) {
  const [todos, setTodos] = useState<Todo[]>([]);
  const addTodo = (title: string) => setTodos([...todos, { title }]);
  return <TodoContext.Provider value={{ todos, addTodo }}>{children}</TodoContext.Provider>;
}

// After (Zustand)
const useTodoStore = create<Store>((set) => ({
  todos: [],
  addTodo: (title) => set((state) => ({ todos: [...state.todos, { title }] })),
}));

// Replace useContext with store hook
const todos = useTodoStore((state) => state.todos);
const addTodo = useTodoStore((state) => state.addTodo);

Quick Reference

Choosing State Management

Local component state → useState
2-3 components nearby → Lift state or Context
App-wide, simple → Zustand
Atomic, derived state → Jotai
Complex, large app → Redux Toolkit
Server data → SWR/React Query

Performance Tips

// ❌ Bad: Entire store subscription
const store = useStore();

// ✅ Good: Selective subscription
const todos = useStore((state) => state.todos);

// ✅ Good: Multiple selectors
const addTodo = useStore((state) => state.addTodo);
const deleteTodo = useStore((state) => state.deleteTodo);

// ✅ Good: Memoized selector
const completedCount = useStore(
  (state) => state.todos.filter((t) => t.completed).length
);

Common Anti-Patterns

❌ Storing server state in global store: Use SWR/React Query instead ✅ Keep server state separate from client state

❌ Too much global state: Most state should be local ✅ Only globalize what needs to be shared

❌ Not splitting context: One context causes all consumers to re-render ✅ Split into multiple contexts (data + actions)

❌ Derived state not memoized: Recalculates on every render ✅ Use useMemo, Jotai derived atoms, or Zustand getters


Level 3: Resources

Comprehensive Reference

  • REFERENCE.md: Complete React state management guide (900+ lines)
    • All state categories (local, shared, server, URL, form)
    • React built-in hooks (useState, useReducer, useContext)
    • External libraries (Zustand, Jotai, Redux Toolkit, MobX, Recoil)
    • Server state (TanStack Query, SWR)
    • URL state management
    • Form state (React Hook Form, Formik)
    • Decision trees and comparison matrices
    • Performance optimization patterns
    • State colocation strategies
    • Immutability patterns
    • Common patterns and anti-patterns

Executable Scripts

Located in resources/scripts/:

  1. analyze_state.py - Analyze React component state patterns

    • Detects state management approaches (useState, useReducer, Context)
    • Identifies prop drilling issues
    • Finds stale closure risks
    • Detects unnecessary derived state
    • Suggests optimization opportunities
    • Reports state complexity metrics
    ./analyze_state.py ./src
    ./analyze_state.py ./src --json
    
  2. benchmark_renders.js - Benchmark render performance

    • Simulates component trees with different state patterns
    • Measures render count and timing
    • Compares useState, Context, Zustand, Jotai
    • Reports performance metrics
    ./benchmark_renders.js
    ./benchmark_renders.js --depth 20 --updates 500
    ./benchmark_renders.js --json
    
  3. detect_unnecessary_renders.js - Detect unnecessary re-renders

    • Identifies components that should use React.memo
    • Finds props that change on every render (object/array literals)
    • Detects missing dependencies in useMemo/useCallback
    • Finds unstable callback props
    • Reports context overuse
    ./detect_unnecessary_renders.js ./src
    ./detect_unnecessary_renders.js ./components --json
    

TypeScript Examples

Located in resources/examples/typescript/:

  1. zustand-store.ts - Complete Zustand patterns

    • Basic store with actions
    • Async operations
    • Slices pattern for large stores
    • Middleware (persist, immer)
    • Selectors and performance
  2. tanstack-query-hooks.ts - TanStack Query (React Query) patterns

    • Basic queries and mutations
    • Optimistic updates
    • Pagination and infinite queries
    • Dependent and parallel queries
    • Query invalidation
    • Cache management
  3. context-provider.tsx - React Context patterns

    • Basic Context
    • Optimized Context (split state/dispatch)
    • Context with useReducer
    • Context composition
    • Selector pattern
    • Performance optimization
  4. react-hook-form-example.tsx - Form state management

    • Basic forms with Zod validation
    • Complex nested fields
    • Field arrays (dynamic forms)
    • Controlled components
    • Custom validation
    • Async validation
  5. immutable-updates.ts - Immutable state patterns

    • Array operations (add, remove, update, sort)
    • Object operations (shallow, nested)
    • Complex state operations
    • Using Immer for complex updates
    • Performance considerations
    • Common patterns

  • react-component-patterns.md - useState, useContext, custom hooks
  • react-data-fetching.md - SWR, React Query for server state
  • nextjs-app-router.md - Server Components (minimal client state)
  • frontend-performance.md - Re-render optimization

Last Updated: 2025-10-27 Format Version: 1.0 (Atomic)