State Management

State Management

Every UI bug is a state bug. The component rendered the wrong thing because it had the wrong data. The question is always: where should this state live, and how does it stay correct?

> Reference: reference/state-patterns.md - State location decision tree, framework comparison, derived state, optimistic updates, state machines, common bugs.

Where State Lives

The Decision Matrix

| Question | If YES → | If NO → | |----------|---------|---------| | Does the server own this data? | Server state | Client state | | Does it persist across page refreshes? | Server or URL state | Component state | | Is it shared across multiple components? | Global/shared state | Local component state | | Should it be bookmarkable/shareable? | URL state | Not URL state |

State Types

| Type | Where | Examples | Tool | |------|-------|---------|------| | Server state | Database, API | User profile, orders, products | React Query, SWR, Apollo, RTK Query | | URL state | Browser URL | Current page, filters, search query, sort order | Router, URLSearchParams | | Global UI state | Memory (store) | Auth status, theme, sidebar open/closed | Zustand, Redux, Jotai, Context | | Local UI state | Component | Input value, dropdown open, hover state | useState, local state | | Form state | Component/library | Field values, validation, dirty/touched | React Hook Form, Formik | | Derived state | Computed | Filtered list, totals, formatted values | Computed/memo, selectors |

The #1 mistake: Putting server state in a global store (Redux, Zustand) and manually keeping it in sync. Use a server state library instead.

Server State

Data that lives on the server and is fetched/cached/synced by the client.

The Pattern

Component needs data
  → Check cache (is it fresh?)
    → YES: render from cache (instant)
    → NO: fetch from server, update cache, render
  → In background: revalidate stale data

Key Concepts

Cache invalidation: When does cached data become stale?

• Time-based: "refetch after 5 minutes" (staleTime)
• Event-based: "refetch after mutation" (invalidate on write)
• Focus-based: "refetch when user returns to tab" (window focus)

Optimistic updates: Show the expected result immediately, rollback if server rejects.

User clicks "Like"
  → Immediately show liked state (optimistic)
  → Send request to server
    → Success: done (UI already correct)
    → Failure: rollback to previous state, show error

Stale-while-revalidate: Show cached (possibly stale) data instantly while fetching fresh data in the background.

Global UI State

State shared across components that doesn't come from the server.

Keep It Small

Most state people put in global stores should be:

• Server state → Use React Query / SWR (not Redux)
• URL state → Use the router (not Redux)
• Local state → Use component state (not Redux)

What actually belongs in a global store:

• Auth state (logged in user, token)
• Theme / appearance preferences
• UI mode (sidebar expanded, notification panel open)
• Feature flags (if client-evaluated)

State Shape

// GOOD: Normalized, flat, minimal
{
  auth: { userId: "123", token: "abc" },
  ui: { sidebarOpen: false, theme: "dark" }
}

// BAD: Nested, duplicated, over-stored
{
  currentUser: { id: "123", name: "Alice", orders: [...], profile: {...} },
  selectedOrder: { ...duplicate of data already in currentUser.orders },
  filteredOrders: [...derived data that should be computed, not stored]
}

Local Component State

State that belongs to a single component and doesn't need to be shared.

Use local state for:

• Input field values (before form submission)
• Toggle states (dropdown open, accordion expanded)
• Hover/focus states
• Animation state
• Temporary UI state (loading spinners, error messages)

Lift state up ONLY when a sibling component needs it. Don't prematurely globalize.

URL State

The URL is state. Treat it as such.

Put in the URL:

• Current page/route
• Search queries and filters
• Sort order
• Pagination (page number)
• Selected tab
• Modal open with ID (/users?edit=123)

Why: Bookmarkable, shareable, browser back button works, survives refresh.

Don't put in the URL:

• Transient UI state (hover, focus)
• Large objects or sensitive data
• State that changes every keystroke (debounce search → URL)

Derived State

State that can be computed from other state. Never store derived state. Compute it.

// BAD: Storing derived state
const [items, setItems] = useState([...]);
const [filteredItems, setFilteredItems] = useState([...]);
// Now you must keep filteredItems in sync with items AND filter criteria

// GOOD: Computing derived state
const [items, setItems] = useState([...]);
const [filter, setFilter] = useState('');
const filteredItems = useMemo(
  () => items.filter(item => item.name.includes(filter)),
  [items, filter]
);

Common Bugs and Fixes

| Bug | Cause | Fix | |-----|-------|-----| | Stale data after mutation | Cache not invalidated | Invalidate/refetch after mutations | | UI flickers on navigation | Showing loading state for cached data | Stale-while-revalidate, keep previous data | | State lost on refresh | State in memory, not URL or server | Put persistent state in URL or server | | Components out of sync | Same data copied in multiple places | Single source of truth, derived state | | Infinite re-render loop | State update in render, missing deps | Fix dependency arrays, move effects | | Race condition on fetch | Slow request returns after fast one | Cancel previous request, use latest | | Zombie child updates | Async callback updates unmounted component | Cleanup in effect, use abort controller |

Anti-Patterns

| Anti-Pattern | Problem | Fix | |-------------|---------|-----| | Everything in Redux/global store | Unnecessary complexity, over-rendering | Match state type to the right location | | Manual server state sync | Stale data, complex update logic | Use server state library (React Query, SWR) | | Storing derived state | Out of sync, extra update logic | Compute with useMemo / selectors | | Prop drilling 8 levels deep | Fragile, hard to refactor | Context for widely-shared state, composition for component trees | | Premature global state | Components coupled to store shape | Start local, lift up only when needed | | Mutable state updates | Subtle bugs, stale closures, no re-render | Immutable updates (spread, immer) |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pvnarp
• Source: pvnarp/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.