React State Management

1---
2name: react-state-management
3description: Master modern React state management with Redux Toolkit, Zustand, Jotai, and React Query. Use when setting up global state, managing server state, or choosing between state management solutions.
4---
5 
6# React State Management
7 
8Comprehensive guide to modern React state management patterns, from local component state to global stores and server state synchronization.
9 
10## Do not use this skill when
11 
12- The task is unrelated to react state management
13- You need a different domain or tool outside this scope
14 
15## Instructions
16 
17- Clarify goals, constraints, and required inputs.
18- Apply relevant best practices and validate outcomes.
19- Provide actionable steps and verification.
20- If detailed examples are required, open `resources/implementation-playbook.md`.
21 
22## Use this skill when
23 
24- Setting up global state management in a React app
25- Choosing between Redux Toolkit, Zustand, or Jotai
26- Managing server state with React Query or SWR
27- Implementing optimistic updates
28- Debugging state-related issues
29- Migrating from legacy Redux to modern patterns
30 
31## Core Concepts
32 
33### 1. State Categories
34 
35| Type | Description | Solutions |
36|------|-------------|-----------|
37| **Local State** | Component-specific, UI state | useState, useReducer |
38| **Global State** | Shared across components | Redux Toolkit, Zustand, Jotai |
39| **Server State** | Remote data, caching | React Query, SWR, RTK Query |
40| **URL State** | Route parameters, search | React Router, nuqs |
41| **Form State** | Input values, validation | React Hook Form, Formik |
42 
43### 2. Selection Criteria
44 
45```
46Small app, simple state → Zustand or Jotai
47Large app, complex state → Redux Toolkit
48Heavy server interaction → React Query + light client state
49Atomic/granular updates → Jotai
50```
51 
52## Quick Start
53 
54### Zustand (Simplest)
55 
56```typescript
57// store/useStore.ts
58import { create } from 'zustand'
59import { devtools, persist } from 'zustand/middleware'
60 
61interface AppState {
62  user: User | null
63  theme: 'light' | 'dark'
64  setUser: (user: User | null) => void
65  toggleTheme: () => void
66}
67 
68export const useStore = create<AppState>()(
69  devtools(
70    persist(
71      (set) => ({
72        user: null,
73        theme: 'light',
74        setUser: (user) => set({ user }),
75        toggleTheme: () => set((state) => ({
76          theme: state.theme === 'light' ? 'dark' : 'light'
77        })),
78      }),
79      { name: 'app-storage' }
80    )
81  )
82)
83 
84// Usage in component
85function Header() {
86  const { user, theme, toggleTheme } = useStore()
87  return (
88    <header className={theme}>
89      {user?.name}
90      <button onClick={toggleTheme}>Toggle Theme</button>
91    </header>
92  )
93}
94```
95 
96## Patterns
97 
98### Pattern 1: Redux Toolkit with TypeScript
99 
100```typescript
101// store/index.ts
102import { configureStore } from '@reduxjs/toolkit'
103import { TypedUseSelectorHook, useDispatch, useSelector } from 'react-redux'
104import userReducer from './slices/userSlice'
105import cartReducer from './slices/cartSlice'
106 
107export const store = configureStore({
108  reducer: {
109    user: userReducer,
110    cart: cartReducer,
111  },
112  middleware: (getDefaultMiddleware) =>
113    getDefaultMiddleware({
114      serializableCheck: {
115        ignoredActions: ['persist/PERSIST'],
116      },
117    }),
118})
119 
120export type RootState = ReturnType<typeof store.getState>
121export type AppDispatch = typeof store.dispatch
122 
123// Typed hooks
124export const useAppDispatch: () => AppDispatch = useDispatch
125export const useAppSelector: TypedUseSelectorHook<RootState> = useSelector
126```
127 
128```typescript
129// store/slices/userSlice.ts
130import { createSlice, createAsyncThunk, PayloadAction } from '@reduxjs/toolkit'
131 
132interface User {
133  id: string
134  email: string
135  name: string
136}
137 
138interface UserState {
139  current: User | null
140  status: 'idle' | 'loading' | 'succeeded' | 'failed'
141  error: string | null
142}
143 
144const initialState: UserState = {
145  current: null,
146  status: 'idle',
147  error: null,
148}
149 
150export const fetchUser = createAsyncThunk(
151  'user/fetchUser',
152  async (userId: string, { rejectWithValue }) => {
153    try {
154      const response = await fetch(`/api/users/${userId}`)
155      if (!response.ok) throw new Error('Failed to fetch user')
156      return await response.json()
157    } catch (error) {
158      return rejectWithValue((error as Error).message)
159    }
160  }
161)
162 
163const userSlice = createSlice({
164  name: 'user',
165  initialState,
166  reducers: {
167    setUser: (state, action: PayloadAction<User>) => {
168      state.current = action.payload
169      state.status = 'succeeded'
170    },
171    clearUser: (state) => {
172      state.current = null
173      state.status = 'idle'
174    },
175  },
176  extraReducers: (builder) => {
177    builder
178      .addCase(fetchUser.pending, (state) => {
179        state.status = 'loading'
180        state.error = null
181      })
182      .addCase(fetchUser.fulfilled, (state, action) => {
183        state.status = 'succeeded'
184        state.current = action.payload
185      })
186      .addCase(fetchUser.rejected, (state, action) => {
187        state.status = 'failed'
188        state.error = action.payload as string
189      })
190  },
191})
192 
193export const { setUser, clearUser } = userSlice.actions
194export default userSlice.reducer
195```
196 
197### Pattern 2: Zustand with Slices (Scalable)
198 
199```typescript
200// store/slices/createUserSlice.ts
201import { StateCreator } from 'zustand'
202 
203export interface UserSlice {
204  user: User | null
205  isAuthenticated: boolean
206  login: (credentials: Credentials) => Promise<void>
207  logout: () => void
208}
209 
210export const createUserSlice: StateCreator<
211  UserSlice & CartSlice, // Combined store type
212  [],
213  [],
214  UserSlice
215> = (set, get) => ({
216  user: null,
217  isAuthenticated: false,
218  login: async (credentials) => {
219    const user = await authApi.login(credentials)
220    set({ user, isAuthenticated: true })
221  },
222  logout: () => {
223    set({ user: null, isAuthenticated: false })
224    // Can access other slices
225    // get().clearCart()
226  },
227})
228 
229// store/index.ts
230import { create } from 'zustand'
231import { createUserSlice, UserSlice } from './slices/createUserSlice'
232import { createCartSlice, CartSlice } from './slices/createCartSlice'
233 
234type StoreState = UserSlice & CartSlice
235 
236export const useStore = create<StoreState>()((...args) => ({
237  ...createUserSlice(...args),
238  ...createCartSlice(...args),
239}))
240 
241// Selective subscriptions (prevents unnecessary re-renders)
242export const useUser = () => useStore((state) => state.user)
243export const useCart = () => useStore((state) => state.cart)
244```
245 
246### Pattern 3: Jotai for Atomic State
247 
248```typescript
249// atoms/userAtoms.ts
250import { atom } from 'jotai'
251import { atomWithStorage } from 'jotai/utils'
252 
253// Basic atom
254export const userAtom = atom<User | null>(null)
255 
256// Derived atom (computed)
257export const isAuthenticatedAtom = atom((get) => get(userAtom) !== null)
258 
259// Atom with localStorage persistence
260export const themeAtom = atomWithStorage<'light' | 'dark'>('theme', 'light')
261 
262// Async atom
263export const userProfileAtom = atom(async (get) => {
264  const user = get(userAtom)
265  if (!user) return null
266  const response = await fetch(`/api/users/${user.id}/profile`)
267  return response.json()
268})
269 
270// Write-only atom (action)
271export const logoutAtom = atom(null, (get, set) => {
272  set(userAtom, null)
273  set(cartAtom, [])
274  localStorage.removeItem('token')
275})
276 
277// Usage
278function Profile() {
279  const [user] = useAtom(userAtom)
280  const [, logout] = useAtom(logoutAtom)
281  const [profile] = useAtom(userProfileAtom) // Suspense-enabled
282 
283  return (
284    <Suspense fallback={<Skeleton />}>
285      <ProfileContent profile={profile} onLogout={logout} />
286    </Suspense>
287  )
288}
289```
290 
291### Pattern 4: React Query for Server State
292 
293```typescript
294// hooks/useUsers.ts
295import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
296 
297// Query keys factory
298export const userKeys = {
299  all: ['users'] as const,
300  lists: () => [...userKeys.all, 'list'] as const,
301  list: (filters: UserFilters) => [...userKeys.lists(), filters] as const,
302  details: () => [...userKeys.all, 'detail'] as const,
303  detail: (id: string) => [...userKeys.details(), id] as const,
304}
305 
306// Fetch hook
307export function useUsers(filters: UserFilters) {
308  return useQuery({
309    queryKey: userKeys.list(filters),
310    queryFn: () => fetchUsers(filters),
311    staleTime: 5 * 60 * 1000, // 5 minutes
312    gcTime: 30 * 60 * 1000, // 30 minutes (formerly cacheTime)
313  })
314}
315 
316// Single user hook
317export function useUser(id: string) {
318  return useQuery({
319    queryKey: userKeys.detail(id),
320    queryFn: () => fetchUser(id),
321    enabled: !!id, // Don't fetch if no id
322  })
323}
324 
325// Mutation with optimistic update
326export function useUpdateUser() {
327  const queryClient = useQueryClient()
328 
329  return useMutation({
330    mutationFn: updateUser,
331    onMutate: async (newUser) => {
332      // Cancel outgoing refetches
333      await queryClient.cancelQueries({ queryKey: userKeys.detail(newUser.id) })
334 
335      // Snapshot previous value
336      const previousUser = queryClient.getQueryData(userKeys.detail(newUser.id))
337 
338      // Optimistically update
339      queryClient.setQueryData(userKeys.detail(newUser.id), newUser)
340 
341      return { previousUser }
342    },
343    onError: (err, newUser, context) => {
344      // Rollback on error
345      queryClient.setQueryData(
346        userKeys.detail(newUser.id),
347        context?.previousUser
348      )
349    },
350    onSettled: (data, error, variables) => {
351      // Refetch after mutation
352      queryClient.invalidateQueries({ queryKey: userKeys.detail(variables.id) })
353    },
354  })
355}
356```
357 
358### Pattern 5: Combining Client + Server State
359 
360```typescript
361// Zustand for client state
362const useUIStore = create<UIState>((set) => ({
363  sidebarOpen: true,
364  modal: null,
365  toggleSidebar: () => set((s) => ({ sidebarOpen: !s.sidebarOpen })),
366  openModal: (modal) => set({ modal }),
367  closeModal: () => set({ modal: null }),
368}))
369 
370// React Query for server state
371function Dashboard() {
372  const { sidebarOpen, toggleSidebar } = useUIStore()
373  const { data: users, isLoading } = useUsers({ active: true })
374  const { data: stats } = useStats()
375 
376  if (isLoading) return <DashboardSkeleton />
377 
378  return (
379    <div className={sidebarOpen ? 'with-sidebar' : ''}>
380      <Sidebar open={sidebarOpen} onToggle={toggleSidebar} />
381      <main>
382        <StatsCards stats={stats} />
383        <UserTable users={users} />
384      </main>
385    </div>
386  )
387}
388```
389 
390## Best Practices
391 
392### Do's
393- **Colocate state** - Keep state as close to where it's used as possible
394- **Use selectors** - Prevent unnecessary re-renders with selective subscriptions
395- **Normalize data** - Flatten nested structures for easier updates
396- **Type everything** - Full TypeScript coverage prevents runtime errors
397- **Separate concerns** - Server state (React Query) vs client state (Zustand)
398 
399### Don'ts
400- **Don't over-globalize** - Not everything needs to be in global state
401- **Don't duplicate server state** - Let React Query manage it
402- **Don't mutate directly** - Always use immutable updates
403- **Don't store derived data** - Compute it instead
404- **Don't mix paradigms** - Pick one primary solution per category
405 
406## Migration Guides
407 
408### From Legacy Redux to RTK
409 
410```typescript
411// Before (legacy Redux)
412const ADD_TODO = 'ADD_TODO'
413const addTodo = (text) => ({ type: ADD_TODO, payload: text })
414function todosReducer(state = [], action) {
415  switch (action.type) {
416    case ADD_TODO:
417      return [...state, { text: action.payload, completed: false }]
418    default:
419      return state
420  }
421}
422 
423// After (Redux Toolkit)
424const todosSlice = createSlice({
425  name: 'todos',
426  initialState: [],
427  reducers: {
428    addTodo: (state, action: PayloadAction<string>) => {
429      // Immer allows "mutations"
430      state.push({ text: action.payload, completed: false })
431    },
432  },
433})
434```
435 
436## Resources
437 
438- [Redux Toolkit Documentation](https://redux-toolkit.js.org/)
439- [Zustand GitHub](https://github.com/pmndrs/zustand)
440- [Jotai Documentation](https://jotai.org/)
441- [TanStack Query](https://tanstack.com/query)
442