import { create } from 'zustand';
import { persist, devtools } from 'zustand/middleware';
import { immer } from 'zustand/middleware/immer';

interface WorkspaceState {
  activeProjectId: string | null;
  sidebarCollapsed: boolean;
  theme: 'light' | 'dark';
  setProject: (id: string) => void;
  toggleSidebar: () => void;
  setTheme: (mode: 'light' | 'dark') => void;
}

export const useWorkspaceStore = create<WorkspaceState>()(
  devtools(
    persist(
      immer((set) => ({
        activeProjectId: null,
        sidebarCollapsed: false,
        theme: 'light',
        setProject: (id) => set({ activeProjectId: id }),
        toggleSidebar: () => set((state) => ({ sidebarCollapsed: !state.sidebarCollapsed })),
        setTheme: (mode) => set({ theme: mode }),
      })),
      { name: 'workspace-config' }
    )
  )
);

import { atom, useAtom } from 'jotai';
import { useWorkspaceStore } from './workspaceStore';

const projectFilterAtom = atom((get) => {
  const theme = useWorkspaceStore.getState().theme;
  const collapsed = useWorkspaceStore.getState().sidebarCollapsed;
  return {
    layoutMode: collapsed ? 'compact' : 'expanded',
    colorScheme: theme === 'dark' ? 'inverted' : 'standard',
  };
});

export const useLayoutConfig = () => useAtom(projectFilterAtom);

anage network requests. We delegate data fetching to a dedicated query layer, keeping the store focused on UI interactions.

import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react';

interface TaskRecord {
  id: string;
  title: string;
  status: 'pending' | 'completed';
  assignee: string;
}

export const taskApi = createApi({
  reducerPath: 'taskApi',
  baseQuery: fetchBaseQuery({ baseUrl: '/api/v1' }),
  tagTypes: ['Task'],
  endpoints: (build) => ({
    fetchTasks: build.query<TaskRecord[], string>({
      query: (projectId) => `projects/${projectId}/tasks`,
      providesTags: ['Task'],
    }),
    updateTaskStatus: build.mutation<void, { id: string; status: string }>({
      query: ({ id, status }) => ({
        url: `tasks/${id}`,
        method: 'PATCH',
        body: { status },
      }),
      invalidatesTags: ['Task'],
    }),
  }),
});

export const { useFetchTasksQuery, useUpdateTaskStatusMutation } = taskApi;

Architecture Rationale: RTK Query handles caching, deduplication, and automatic refetching. By invalidating tags on mutations, we ensure UI consistency without manual store updates. This separation prevents state synchronization bugs and keeps the client store lightweight. The query layer integrates seamlessly with React's rendering cycle through custom hooks that manage loading, error, and data states.

Step 4: Compose in Components

Components consume state through targeted selectors or atomic hooks, avoiding unnecessary subscriptions.

import { useWorkspaceStore } from './workspaceStore';
import { useLayoutConfig } from './layoutAtoms';
import { useFetchTasksQuery } from './taskApi';

export function TaskBoard() {
  const projectId = useWorkspaceStore((s) => s.activeProjectId);
  const { data: tasks, isLoading } = useFetchTasksQuery(projectId ?? '', { skip: !projectId });
  const [layout] = useLayoutConfig();

  if (!projectId) return <div>Select a project to view tasks.</div>;
  if (isLoading) return <div>Loading tasks...</div>;

  return (
    <div className={`board ${layout.layoutMode} ${layout.colorScheme}`}>
      {tasks?.map((t) => (
        <TaskCard key={t.id} task={t} />
      ))}
    </div>
  );
}

Architecture Rationale: Selectors extract only the required slice, preventing re-renders when unrelated state changes. The query hook manages network lifecycle independently. The atomic hook provides computed layout configuration without coupling to the global store's update cycle. This composition pattern ensures predictable rendering, clear data flow, and maintainable component boundaries.

Pitfall Guide

1. The Monolithic Store Trap

Explanation: Developers consolidate all application data into a single store, including server responses, form inputs, and UI toggles. This creates a bloated state tree, increases serialization overhead, and triggers unnecessary re-renders across unrelated components. Fix: Separate server state, client state, and ephemeral UI state. Use a query layer for network data, a global store for shared client state, and local useState for component-specific inputs.

2. Atom Sprawl & Dependency Chaos

Explanation: Atomic libraries encourage creating a primitive for every piece of data. Without conventions, teams generate hundreds of atoms with implicit dependencies, making debugging and refactoring difficult. Fix: Group related atoms into modules. Use derived atoms for computed values instead of manual synchronization. Establish a naming convention that reflects data domain (e.g., userPrefsAtom, filterStateAtom) and limit top-level atoms to shared state only.

3. Ignoring Server/Client State Separation

Explanation: Treating API responses as regular state leads to manual cache invalidation, race conditions, and duplicated loading/error logic across components. Fix: Delegate data fetching to RTK Query or TanStack Query. Keep the client store focused on interactions, preferences, and navigation state. Use query hooks for network data and store hooks for UI state.

4. Over-Optimizing Selectors

Explanation: Developers create highly granular selectors for every component, assuming finer granularity always improves performance. This increases code complexity and can degrade performance due to selector recomputation overhead. Fix: Profile re-renders before optimizing. Use coarse selectors for low-frequency updates and fine-grained selectors only for performance-critical paths. Memoize expensive computations with useMemo or derived atoms.

5. TypeScript Type Drift in Middleware

Explanation: Middleware pipelines often strip or alter type information, leading to any fallbacks or manual type assertions. This breaks autocompletion and increases refactoring risk. Fix: Define store interfaces explicitly before applying middleware. Use generic type parameters in middleware wrappers to preserve inference. Validate types in CI with strict compiler flags and avoid casting to any.

6. DevTools Blind Spots

Explanation: Custom middleware or manual state mutations bypass debugging tools, making it impossible to trace state changes or reproduce bugs. Fix: Always wrap stores with devtools middleware. Avoid direct state mutations outside the store's update function. Use action logging for async flows and verify that time-travel debugging captures all state transitions.

7. Mixing Async Patterns

Explanation: Combining createAsyncThunk, manual useEffect fetches, and atomic async getters creates inconsistent error handling, loading states, and cache invalidation logic. Fix: Standardize on a single async pattern per project. Use RTK Query for REST/GraphQL data, createAsyncThunk for side effects that update client state, and avoid mixing manual fetches with declarative query layers.

Production Bundle

Action Checklist

• Audit current state usage: Identify server data, shared client state, and local UI state.
• Separate concerns: Route network requests to a query layer, keep client state in a global store, use local state for component inputs.
• Define explicit interfaces: Create TypeScript types for all store slices, atoms, and API responses before implementation.
• Compose middleware intentionally: Apply persistence, devtools, and immutability wrappers only where needed.
• Implement selector boundaries: Extract only required state slices in components to prevent unnecessary re-renders.
• Establish atomic conventions: Group related primitives, use derived atoms for computations, and limit top-level atoms.
• Validate async flows: Standardize on a single data fetching pattern and remove manual useEffect fetches.
• Profile before optimizing: Measure re-render frequency and bundle impact before introducing granular selectors or memoization.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Solo developer or small team building a new app	Hook-Based Global Store	Minimal boilerplate, fast iteration, excellent TS inference	Low initial cost, scales well up to ~50k LOC
Enterprise team with strict code review standards	Centralized Store	Explicit data flow, generated types, native debugging	Higher upfront cost, reduces long-term maintenance risk
UI with complex derived calculations or cascading filters	Atomic Primitives	Fine-grained re-renders, lazy computation, composable dependencies	Moderate learning curve, optimizes rendering performance
Heavy data fetching with caching requirements	RTK Query / TanStack Query	Automatic deduplication, cache invalidation, loading/error states	Decouples network logic, reduces client store size
Legacy codebase migrating from older Redux patterns	Centralized Store (RTK)	Drop-in replacement, preserves existing architecture, gradual migration	Low migration friction, maintains team familiarity

Configuration Template

// store/index.ts
import { configureStore } from '@reduxjs/toolkit';
import { setupListeners } from '@reduxjs/toolkit/query';
import { taskApi } from './taskApi';
import { userApi } from './userApi';

export const appStore = configureStore({
  reducer: {
    [taskApi.reducerPath]: taskApi.reducer,
    [userApi.reducerPath]: userApi.reducer,
  },
  middleware: (getDefault) =>
    getDefault().concat(taskApi.middleware, userApi.middleware),
});

setupListeners(appStore.dispatch);

export type AppDispatch = typeof appStore.dispatch;
export type RootState = ReturnType<typeof appStore.getState>;

// store/workspace.ts
import { create } from 'zustand';
import { persist, devtools, immer } from 'zustand/middleware';

interface WorkspaceConfig {
  activeWorkspace: string | null;
  preferences: {
    notifications: boolean;
    autoSave: boolean;
  };
  setWorkspace: (id: string) => void;
  updatePreferences: (patch: Partial<WorkspaceConfig['preferences']>) => void;
}

export const useWorkspaceConfig = create<WorkspaceConfig>()(
  devtools(
    persist(
      immer((set) => ({
        activeWorkspace: null,
        preferences: { notifications: true, autoSave: true },
        setWorkspace: (id) => set({ activeWorkspace: id }),
        updatePreferences: (patch) =>
          set((state) => {
            state.preferences = { ...state.preferences, ...patch };
          }),
      })),
      { name: 'workspace-preferences' }
    )
  )
);

Quick Start Guide

1. Initialize the project structure: Create separate directories for store/client, store/server, and store/atoms. This enforces separation of concerns from day one.
2. Install dependencies: Add zustand, jotai, @reduxjs/toolkit, and @reduxjs/toolkit/query/react to your project. Configure TypeScript with strict mode enabled.
3. Define your first store: Create a client state store using the hook-based pattern. Add middleware for persistence and devtools. Export a custom hook for component consumption.
4. Set up the query layer: Configure RTK Query with a base URL and tag types. Define endpoints for your primary resources. Export generated hooks for components.
5. Wire components to state: Replace useState and useEffect fetches with store selectors and query hooks. Verify that re-renders only occur when subscribed data changes.