Redux Toolkit skill for Codex

Done well means: the store is built with configureStore, every reducer is a slice, components use typed hooks and memoized selectors, server data goes through RTK Query with explicit tags instead of hand-written thunks and loading flags, and legacy code is migrated reducer by reducer with the app working at every step.

Before you start

1. Read AGENTS.md, then versions: npm ls @reduxjs/toolkit react-redux redux. RTK 2 requires the builder callback for extraReducers and createReducer (the object syntax was removed), ships Reselect 5 and Redux 5, and pairs with React-Redux 9.
2. Locate the store setup and list reducers: grep -rn "combineReducers\|configureStore\|createStore" src.
3. Check how server data is fetched today (thunks, sagas, RTK Query, TanStack Query). Do not introduce a second server-state library without agreement.

Store and typed hooks

// src/app/store.ts
import { configureStore } from "@reduxjs/toolkit";
import { setupListeners } from "@reduxjs/toolkit/query";
import { api } from "./api";
import { uiSlice } from "@/features/ui/ui-slice";

export const makeStore = () =>
  configureStore({
    reducer: { [uiSlice.reducerPath]: uiSlice.reducer, [api.reducerPath]: api.reducer },
    middleware: (getDefault) => getDefault().concat(api.middleware),
  });

export const store = makeStore();
setupListeners(store.dispatch); // refetchOnFocus / refetchOnReconnect support

export type AppStore = ReturnType<typeof makeStore>;
export type RootState = ReturnType<AppStore["getState"]>;
export type AppDispatch = AppStore["dispatch"];

// src/app/hooks.ts
import { useDispatch, useSelector, useStore } from "react-redux";
import type { AppDispatch, AppStore, RootState } from "./store";

export const useAppDispatch = useDispatch.withTypes<AppDispatch>();
export const useAppSelector = useSelector.withTypes<RootState>();
export const useAppStore = useStore.withTypes<AppStore>();

For Next.js App Router, create the store per request with makeStore() inside a client provider (useRef/useState initializer); never export a module-level store that the server reuses across users.

Slices

import { createSlice, createAsyncThunk, type PayloadAction } from "@reduxjs/toolkit";

type UiState = { sidebarOpen: boolean; toasts: Toast[] };
const initialState: UiState = { sidebarOpen: true, toasts: [] };

export const uiSlice = createSlice({
  name: "ui",
  initialState,
  reducers: {
    toggleSidebar: (state) => { state.sidebarOpen = !state.sidebarOpen; }, // Immer: mutate the draft
    toastAdded: {
      reducer: (state, action: PayloadAction<Toast>) => { state.toasts.push(action.payload); },
      prepare: (message: string) => ({ payload: { id: nanoid(), message } }),
    },
  },
  extraReducers: (builder) => {
    builder.addCase(logout.fulfilled, () => initialState);
  },
  selectors: {
    selectSidebarOpen: (state) => state.sidebarOpen,
  },
});

export const { toggleSidebar, toastAdded } = uiSlice.actions;
export const { selectSidebarOpen } = uiSlice.selectors;

• Inside reducers, either mutate the draft or return a new value, never both.
• Name actions as past-tense events (toastAdded, orderSubmitted) when several slices react to them; setter names (setX) are fine for slice-local UI state.
• Non-serializable values (Dates, class instances, Promises, functions) in state or actions trigger the serializability middleware warning; store ISO strings and IDs.
• Normalized collections: createEntityAdapter gives ids/entities, CRUD reducers and getSelectors.

Selectors

• Select the smallest value: useAppSelector((s) => s.ui.sidebarOpen).
• Selectors that return new arrays or objects (filter, map) must be memoized with createSelector, or the component re-renders on every dispatch. React-Redux 9 warns in development when a selector returns a different reference for the same input.

export const selectVisibleTodos = createSelector(
  [(s: RootState) => s.todos.items, (s: RootState) => s.todos.filter],
  (items, filter) => items.filter((t) => (filter === "done" ? t.done : !t.done)),
);

RTK Query for server data

// src/app/api.ts
import { createApi, fetchBaseQuery } from "@reduxjs/toolkit/query/react";

export const api = createApi({
  reducerPath: "api",
  baseQuery: fetchBaseQuery({ baseUrl: "/api", credentials: "include" }),
  tagTypes: ["Project"],
  keepUnusedDataFor: 60, // seconds an unused cache entry survives (default 60)
  endpoints: (build) => ({
    getProjects: build.query<Project[], { status: string }>({
      query: ({ status }) => ({ url: "projects", params: { status } }),
      providesTags: (result) =>
        result
          ? [...result.map((p) => ({ type: "Project" as const, id: p.id })), { type: "Project", id: "LIST" }]
          : [{ type: "Project", id: "LIST" }],
    }),
    getProject: build.query<Project, string>({
      query: (id) => `projects/${id}`,
      providesTags: (_r, _e, id) => [{ type: "Project", id }],
    }),
    renameProject: build.mutation<Project, { id: string; name: string }>({
      query: ({ id, name }) => ({ url: `projects/${id}`, method: "PATCH", body: { name } }),
      invalidatesTags: (_r, _e, { id }) => [{ type: "Project", id }, { type: "Project", id: "LIST" }],
    }),
  }),
});

export const { useGetProjectsQuery, useGetProjectQuery, useRenameProjectMutation } = api;

• The LIST tag pattern makes creates and deletes refresh lists while edits refresh only the affected item.
• Optimistic update: in onQueryStarted, call dispatch(api.util.updateQueryData("getProject", id, (draft) => { draft.name = name })), then await queryFulfilled in a try/catch and call patch.undo() on failure.
• Conditional fetching: pass skipToken as the argument instead of a skip flag when the argument may be undefined; it keeps types narrow.
• Use isLoading for the first load and isFetching for background refetches.
• For large APIs, split endpoints across files with api.injectEndpoints.
• Generate endpoints from an OpenAPI spec with @rtk-query/codegen-openapi when the backend publishes one.

Side effects

Prefer createListenerMiddleware over sagas for new reactive logic (sync to storage, analytics, debounced autosave). Use createAsyncThunk for non-cache async flows such as multi-step checkout. Keep existing sagas or observables unless the task is to remove them.

Migrating legacy Redux

- [ ] 1. Replace createStore + applyMiddleware + compose with configureStore
- [ ] 2. Keep old reducers mounted as-is; confirm the app works
- [ ] 3. Convert one reducer at a time to createSlice, keeping action type strings if
         other code dispatches them by string
- [ ] 4. Replace hand-written thunks that fetch data with RTK Query endpoints
- [ ] 5. Move connect() components to hooks when you touch them
- [ ] 6. Delete action type constants and action creator files once unused

• configureStore adds thunk and dev-only immutability and serializability checks. The checks will surface existing mutations in old reducers; fix them, do not disable the middleware.
• To keep compatibility while converting, a slice can respond to old string actions in extraReducers with builder.addCase("todos/ADD_TODO", ...) or addMatcher.
• connect still works in React-Redux 9; migrate it opportunistically, not in one sweep.
• Codemods for RTK 2 syntax changes are published as @reduxjs/rtk-codemods; running them via npx needs network access.

Gotchas

• Two store instances (one in tests, one in the app module) lead to tests passing while the app is wrong. Build both with makeStore().
• Putting RTK Query data into a slice by listening to fulfilled actions duplicates the cache; read from the query hook or api.endpoints.x.select(arg).
• Forgetting api.middleware makes queries fetch once and never refetch, poll or expire.
• Tag matching is asymmetric: invalidating bare "Project" refreshes every query that provides any Project tag, while invalidating { type: "Project", id } refreshes only queries that provided that id or the bare "Project" tag. Write the provide and invalidate matrix down when lists refresh too much or too little.

Verification

• Type-check passes; no any in RootState.
• Redux DevTools: actions have meaningful names; no serializability or mutation warnings in the console.
• After each mutation, only the expected queries refetch (DevTools RTK Query tab or Network panel).
• Tests create a fresh store per test via makeStore().

Output

For new code: slices with their actions and selectors, endpoints with provided and invalidated tags. For migrations: a checklist of reducers converted, thunks replaced, and remaining legacy pieces.