React State Management Specialist

Specialized in managing application state using React Context API for client state and TanStack Query for server state.

When to Use This Skill

• Managing global client state (user preferences, UI state, etc.)
• Implementing server state management with caching and revalidation
• Coordinating state across multiple components
• Implementing optimistic updates for better UX
• Choosing between local, global, client, and server state
• Normalizing state for efficient updates

Core Principles

• Local First: Prefer local state when possible
• Lift State Up: Move state to common ancestor when needed
• Separate Client/Server State: Use Context for client, TanStack Query for server
• Single Source of Truth: Avoid state duplication
• Optimistic UI: Update UI immediately, sync with server later
• Data Normalization: Structure state for efficient access and updates

Implementation Guidelines

State Selection Guidelines

// Local state - Component-specific, doesn't need to be shared
const [isOpen, setIsOpen] = useState(false)
const [searchQuery, setSearchQuery] = useState('')

// Lifted state - Shared among child components
const Parent = () => {
  const [selectedId, setSelectedId] = useState<string | null>(null)
  return (
    <>
      <List onSelect={setSelectedId} />
      <Detail id={selectedId} />
    </>
  )
}

// Global client state - App-wide UI state, user preferences
// Use Context API
const theme = useTheme() // 'light' | 'dark'
const locale = useLocale() // 'en' | 'ja'

// Server state - Data from API, needs caching and revalidation
// Use TanStack Query
const { data: users } = useQuery({ queryKey: ['users'], queryFn: fetchUsers })

Context API for Global Client State

import { createContext, useContext, useState, ReactNode } from 'react'

// 1. Define context value type
interface ThemeContextValue {
  theme: 'light' | 'dark'
  toggleTheme: () => void
}

// 2. Create context with undefined default
const ThemeContext = createContext<ThemeContextValue | undefined>(undefined)

// 3. Create provider component
export const ThemeProvider = ({ children }: { children: ReactNode }) => {
  const [theme, setTheme] = useState<'light' | 'dark'>(() => {
    // WHY: Initialize from localStorage for persistence
    const saved = localStorage.getItem('theme')
    return (saved === 'dark' ? 'dark' : 'light')
  })

  const toggleTheme = () => {
    setTheme(prev => {
      const newTheme = prev === 'light' ? 'dark' : 'light'
      localStorage.setItem('theme', newTheme)
      return newTheme
    })
  }

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

// 4. Create custom hook for consuming context
export const useTheme = (): ThemeContextValue => {
  const context = useContext(ThemeContext)
  if (!context) {
    throw new Error('useTheme must be used within ThemeProvider')
  }
  return context
}

// 5. Usage in app
const App = () => {
  return (
    <ThemeProvider>
      <Dashboard />
    </ThemeProvider>
  )
}

// 6. Usage in components
const Dashboard = () => {
  const { theme, toggleTheme } = useTheme()

  return (
    <div className={theme === 'light' ? 'light-mode' : 'dark-mode'}>
      <button onClick={toggleTheme}>Toggle Theme</button>
    </div>
  )
}

Complex Context with useReducer

// State and actions
type State = {
  user: User | null
  isAuthenticated: boolean
  loading: boolean
}

type Action =
  | { type: 'LOGIN_START' }
  | { type: 'LOGIN_SUCCESS'; payload: User }
  | { type: 'LOGIN_FAILURE' }
  | { type: 'LOGOUT' }

// Reducer
function authReducer(state: State, action: Action): State {
  switch (action.type) {
    case 'LOGIN_START':
      return { ...state, loading: true }
    case 'LOGIN_SUCCESS':
      return {
        ...state,
        user: action.payload,
        isAuthenticated: true,
        loading: false,
      }
    case 'LOGIN_FAILURE':
      return { ...state, loading: false }
    case 'LOGOUT':
      return { user: null, isAuthenticated: false, loading: false }
    default:
      return state
  }
}

// Context value
interface AuthContextValue {
  state: State
  login: (email: string, password: string) => Promise<void>
  logout: () => void
}

const AuthContext = createContext<AuthContextValue | undefined>(undefined)

// Provider
export const AuthProvider = ({ children }: { children: ReactNode }) => {
  const [state, dispatch] = useReducer(authReducer, {
    user: null,
    isAuthenticated: false,
    loading: false,
  })

  const login = async (email: string, password: string) => {
    dispatch({ type: 'LOGIN_START' })
    try {
      const user = await api.login(email, password)
      dispatch({ type: 'LOGIN_SUCCESS', payload: user })
    } catch {
      dispatch({ type: 'LOGIN_FAILURE' })
    }
  }

  const logout = () => {
    api.logout()
    dispatch({ type: 'LOGOUT' })
  }

  return (
    <AuthContext.Provider value={{ state, login, logout }}>
      {children}
    </AuthContext.Provider>
  )
}

export const useAuth = () => {
  const context = useContext(AuthContext)
  if (!context) {
    throw new Error('useAuth must be used within AuthProvider')
  }
  return context
}

TanStack Query for Server State

// Setup QueryClient
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 5 * 60 * 1000, // 5 minutes
      cacheTime: 10 * 60 * 1000, // 10 minutes
      refetchOnWindowFocus: false,
    },
  },
})

export const App = () => {
  return (
    <QueryClientProvider client={queryClient}>
      <Dashboard />
    </QueryClientProvider>
  )
}

// Basic query
import { useQuery } from '@tanstack/react-query'

export const UserList = () => {
  const {
    data: users,
    isLoading,
    error,
  } = useQuery({
    queryKey: ['users'],
    queryFn: async () => {
      const response = await fetch('/api/users')
      if (!response.ok) throw new Error('Failed to fetch')
      return response.json()
    },
  })

  if (isLoading) return <div>Loading...</div>
  if (error) return <div>Error: {error.message}</div>

  return (
    <ul>
      {users.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  )
}

// Query with parameters
export const UserDetail = ({ userId }: { userId: string }) => {
  const { data: user } = useQuery({
    queryKey: ['users', userId],
    queryFn: () => fetchUser(userId),
    // WHY: Don't fetch if userId is null
    enabled: !!userId,
  })

  return <div>{user?.name}</div>
}

// Dependent queries
export const UserOrders = ({ userId }: { userId: string }) => {
  const { data: user } = useQuery({
    queryKey: ['users', userId],
    queryFn: () => fetchUser(userId),
  })

  // WHY: Only fetch orders after user is loaded
  const { data: orders } = useQuery({
    queryKey: ['orders', userId],
    queryFn: () => fetchOrders(userId),
    enabled: !!user,
  })

  return <div>...</div>
}

Mutations with TanStack Query

import { useMutation, useQueryClient } from '@tanstack/react-query'

export const CreateUserForm = () => {
  const queryClient = useQueryClient()

  const mutation = useMutation({
    mutationFn: (newUser: NewUser) => {
      return fetch('/api/users', {
        method: 'POST',
        body: JSON.stringify(newUser),
      }).then(res => res.json())
    },
    onSuccess: () => {
      // WHY: Invalidate and refetch users list after creation
      queryClient.invalidateQueries({ queryKey: ['users'] })
    },
  })

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault()
    mutation.mutate({ name: 'John', email: 'john@example.com' })
  }

  return (
    <form onSubmit={handleSubmit}>
      {/* form fields */}
      <button disabled={mutation.isPending}>
        {mutation.isPending ? 'Creating...' : 'Create User'}
      </button>
      {mutation.isError && <div>Error: {mutation.error.message}</div>}
    </form>
  )
}

Optimistic Updates

export const TodoList = () => {
  const queryClient = useQueryClient()

  const toggleMutation = useMutation({
    mutationFn: async (todoId: string) => {
      return fetch(`/api/todos/${todoId}/toggle`, { method: 'POST' })
    },
    // WHY: Update UI immediately for better UX
    onMutate: async (todoId) => {
      // Cancel outgoing refetches
      await queryClient.cancelQueries({ queryKey: ['todos'] })

      // Snapshot previous value
      const previousTodos = queryClient.getQueryData(['todos'])

      // Optimistically update
      queryClient.setQueryData(['todos'], (old: Todo[]) =>
        old.map(todo =>
          todo.id === todoId
            ? { ...todo, completed: !todo.completed }
            : todo
        )
      )

      // Return context for rollback
      return { previousTodos }
    },
    onError: (err, todoId, context) => {
      // WHY: Rollback on error
      queryClient.setQueryData(['todos'], context?.previousTodos)
    },
    onSettled: () => {
      // WHY: Refetch to ensure consistency
      queryClient.invalidateQueries({ queryKey: ['todos'] })
    },
  })

  return <div>...</div>
}

State Normalization

// Bad: Nested structure makes updates difficult
type State = {
  posts: Array<{
    id: string
    title: string
    author: {
      id: string
      name: string
    }
    comments: Array<{
      id: string
      text: string
      author: {
        id: string
        name: string
      }
    }>
  }>
}

// Good: Normalized structure
type NormalizedState = {
  users: Record<string, User>
  posts: Record<string, Post>
  comments: Record<string, Comment>
}

// Selector to get post with relations
function selectPostWithRelations(state: NormalizedState, postId: string) {
  const post = state.posts[postId]
  return {
    ...post,
    author: state.users[post.authorId],
    comments: post.commentIds.map(id => ({
      ...state.comments[id],
      author: state.users[state.comments[id].authorId],
    })),
  }
}

// Update is simpler
function updateUser(state: NormalizedState, userId: string, updates: Partial<User>) {
  return {
    ...state,
    users: {
      ...state.users,
      [userId]: { ...state.users[userId], ...updates },
    },
  }
}

Combining Context and TanStack Query

// Use Context for derived UI state
interface UIContextValue {
  selectedUserId: string | null
  setSelectedUserId: (id: string | null) => void
}

const UIContext = createContext<UIContextValue | undefined>(undefined)

export const UIProvider = ({ children }: { children: ReactNode }) => {
  const [selectedUserId, setSelectedUserId] = useState<string | null>(null)

  return (
    <UIContext.Provider value={{ selectedUserId, setSelectedUserId }}>
      {children}
    </UIContext.Provider>
  )
}

// Use TanStack Query for server data
export const UserDashboard = () => {
  const { selectedUserId } = useUI()
  const { data: users } = useQuery({
    queryKey: ['users'],
    queryFn: fetchUsers,
  })

  const { data: selectedUser } = useQuery({
    queryKey: ['users', selectedUserId],
    queryFn: () => fetchUser(selectedUserId!),
    enabled: !!selectedUserId,
  })

  return (
    <div>
      <UserList users={users} />
      {selectedUser && <UserDetail user={selectedUser} />}
    </div>
  )
}

Tools to Use

• Read: Read existing context providers and queries
• Write: Create new state management code
• Edit: Update state management logic
• Bash: Run tests and type checker

Bash Commands

# Type checking
tsc --noEmit

# Run tests
vitest

# Run development server
vite

Workflow

1. Identify State Type: Determine if state is local, global client, or server
2. Choose Solution: Use local state, Context API, or TanStack Query
3. Write Tests First: Test state management logic with TDD
4. Implement State: Create context providers or queries
5. Test Integration: Ensure components work with state
6. Optimize: Add memoization if needed
7. Commit: Create atomic commit

Related Skills

• react-component-development: For component integration
• vitest-react-testing: For testing state logic
• typescript-core-development: For type-safe state

Coding Standards

See React Coding Standards

TDD Workflow

Follow Frontend TDD Workflow

Key Reminders

• Prefer local state when possible, lift state up when needed
• Use Context API for global client state (theme, locale, UI state)
• Use TanStack Query for server state (API data, caching)
• Implement optimistic updates for better UX
• Normalize state for efficient updates
• Always provide custom hooks for consuming context
• Throw error if context is used outside provider
• Use useReducer for complex state logic
• Invalidate queries after mutations
• Set staleTime and cacheTime appropriately
• Enable queries conditionally when needed
• Test state management logic thoroughly
• Write comments explaining WHY, not WHAT