nextjs-state-management

---
name: nextjs-state-management
description: Apply best practices for managing URL, server, and client state in Next.js applications. Use when choosing between URL params, SWR/TanStack Query, Zustand, or Context for state, or when fixing hydration mismatches from localStorage.
metadata:
  triggers:
    files:
    - '**/hooks/*.ts'
    - '**/store.ts'
    - '**/components/*.tsx'
    keywords:
    - useState
    - useContext
    - zustand
    - redux
---
# State Management

## **Priority: P2 (MEDIUM)**

## Decision Guide

1. **Shareable/persistent?** Use URL state (`useSearchParams` + `useRouter`).
2. **Server data?** Use SWR or TanStack Query. Never sync into `useState`.
3. **Complex client UI?** Use Zustand (in `'use client'` only) or Jotai.
4. **Simple local?** Use `useState`. Colocate as close to consumer as possible.

## URL-Driven State

See [implementation examples](references/implementation.md)

## Server State (SWR / TanStack Query)

See [implementation examples](references/implementation.md)

## Client State (Zustand)

See [implementation examples](references/implementation.md)

## Hydration Safety

Wrap `localStorage` reads in `useEffect` or `mounted` flag to avoid hydration mismatches. Manage optimistic updates with `useOptimistic` in Next.js 15+.

## Legacy Redux (existing projects)

If project already uses `redux@4` + `createStore` + `redux-thunk` + `next-redux-wrapper`:

- Use `useSelector` / `useDispatch` hooks — never connect HOC.
- Define typed `RootState` and typed `AppDispatch` for all selectors and dispatch calls.
- Avoid adding Zustand or TanStack Query on top of existing Redux codebase — migrate incrementally if needed.
- Migration path: Redux Toolkit (`@reduxjs/toolkit`) → RTK Query → then consider TanStack Query.

See [references/redux.md](references/redux.md) for typed selector and thunk patterns.

## Library Patterns

- [references/redux.md](references/redux.md)
- [references/zustand.md](references/zustand.md)
- [references/url-state.md](references/url-state.md)

## Anti-Patterns

- **No global store for simple state**: Use `useState` or URL params; avoid Zustand for basic UI.
- **No large objects in state**: Decompose into granular primitives to prevent extra re-renders.
- **No `useEffect` for data fetching**: Use SWR or TanStack Query for server state.
- **No server state in client stores**: Fetch in RSCs; client stores for UI-only state.