| name | migrate-state-management |
| description | Migrate Redux or React Context to the correct state option (React Query for server state, nuqs for URL/shareable state, Zustand for global client state). Use when refactoring away from Redux/Context, moving state to the right store, or when the user asks to migrate state management. |
Migrate State: Redux/Context → React Query, nuqs, Zustand
Do not introduce or recommend Redux or React Context. Migrate existing usage to the stack below.
1. Classify the state
Before changing code, classify what the state represents:
| If the state is… | Migrate to | Do not use |
|---|
| From API / server (versions, configs, fetched lists, time-series) | React Query | Redux, Context |
| Shareable via URL (filters, time range, page, selected ids) | nuqs | Redux, Context |
| Global/client UI (dashboard lock, query builder, feature flags, large client objects) | Zustand | Redux, Context |
| Local to one component (inputs, toggles, hover) | useState / useReducer | Zustand, Redux, Context |
If one slice mixes concerns (e.g. Redux has both API data and pagination), split: API → React Query, pagination → nuqs, rest → Zustand or local state.
2. Migrate to React Query (server state)
When: State comes from or mirrors an API response (e.g. currentVersion, latestVersion, configs, lists).
Steps:
- Find where the data is fetched (existing
useQuery/API call) and where it is dispatched or set in Context/Redux.
- Remove the dispatch/set that writes API results into Redux/Context.
- Expose a single hook that uses the query and returns the same shape consumers expect (use
useMemo for derived objects like configs to avoid unnecessary re-renders).
- Replace Redux/Context consumption with the new hook. Prefer generated React Query hooks from
frontend/src/api/generated when available.
- Configure cache/refetch (e.g.
refetchOnMount: false, staleTime) so behavior matches previous “single source” expectations.
Before (Redux mirroring React Query):
if (getUserLatestVersionResponse.isFetched && getUserLatestVersionResponse.isSuccess && getUserLatestVersionResponse.data?.payload) {
dispatch({ type: UPDATE_LATEST_VERSION, payload: { latestVersion: getUserLatestVersionResponse.data.payload.tag_name } })
}
After (single source in React Query):
export function useAppStateHook() {
const { data, isError } = useQuery(...)
const memoizedConfigs = useMemo(() => ({ ... }), [data?.configs])
return {
latestVersion: data?.payload?.tag_name,
configs: memoizedConfigs,
isError,
}
}
Consumers use useAppStateHook() instead of useSelector or Context. Do not copy React Query result into Redux or Context.
3. Migrate to nuqs (URL / shareable state)
When: State should be in the URL: filters, time range, pagination, selected values, view state. Keep payload small (e.g. Chrome ~2k chars); no large datasets or sensitive data.
Steps:
- Identify which Redux/Context fields are shareable or already reflected in the URL (e.g.
currentPage, timeRange, selectedFilter).
- Add nuqs (or use existing):
useQueryState('param', parseAsString.withDefault('…')) (or parseAsInteger, etc.).
- Replace reads/writes of those fields with nuqs hooks. Use typed parsers; avoid ad-hoc
useSearchParams encoding/decoding.
- Remove the same fields from Redux/Context and their reducers/providers.
Before (Context/Redux):
const { timeRange } = useContext(SomeContext)
const [page, setPage] = useDispatch(...)
After (nuqs):
const [timeRange, setTimeRange] = useQueryState('timeRange', parseAsString.withDefault('1h'))
const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1))
4. Migrate to Zustand (global client state)
When: State is global or cross-component client state: feature flags, dashboard state, query builder state, complex/large client objects (e.g. up to ~1.5–2MB). Not for server cache or local-only UI.
Steps:
- Create one store per domain (e.g.
DashboardStore, QueryBuilderStore). One create() per module; for large state use slice factories and combine.
- Put state properties first, then actions. Use
set (or setState / getState() + set) for updates; never mutate state directly.
- Replace Context/Redux consumption with the store hook and a selector so only the used slice triggers re-renders.
- Remove the old Context provider / Redux slice and related dispatches.
Selector (required):
const isLocked = useDashboardStore(state => state.isDashboardLocked)
Never use useStore() with no selector. Never do state.foo = x inside actions; use set(state => ({ ... })).
Before (Context/Redux):
const { isDashboardLocked, setLocked } = useContext(DashboardContext)
After (Zustand):
const isLocked = useDashboardStore(state => state.isDashboardLocked)
const setLocked = useDashboardStore(state => state.setLocked)
For large stores (many top-level fields), split into slices and combine:
const createBearSlice = set => ({ bears: 0, addBear: () => set(s => ({ bears: s.bears + 1 })) })
const useStore = create(set => ({ ...createBearSlice(set), ...createFishSlice(set) }))
Add eslint-plugin-zustand-rules with plugin:zustand-rules/recommended to enforce selectors and no direct mutation.
5. Migrate to local state (useState / useReducer)
When: State is used only inside one component or a small subtree (form inputs, toggles, hover, panel selection). No URL sync, no cross-feature sharing.
Steps:
- Move the state into the component that owns it (or the smallest common parent).
- Use
useState or useReducer (useReducer when multiple related fields change together).
- Remove from Redux/Context and any provider/slice.
Do not use Zustand, Redux, or Context for purely local UI state.
6. Migration checklist
Additional resources