Zustand bukan tempat semua state.
Zustand adalah external store untuk state client yang:
- perlu dibaca lintas subtree,
- berubah cukup sering,
- tidak cocok di Context karena fan-out,
- bukan otoritas server,
- punya lifecycle lebih panjang dari satu component,
- dan butuh subscription granular.

Apakah kita pakai Zustand?

State ini milik siapa?
Berapa luas radius pembacanya?
Siapa yang boleh mengubahnya?
Apakah state ini otoritatif dari server?
Apakah perlu survive navigation?
Apakah perubahan kecil boleh memicu rerender banyak component?

- store berada di luar React tree,
- component bisa subscribe ke selector tertentu,
- action bisa didefinisikan bersama state,
- tidak perlu reducer boilerplate,
- middleware bisa menambah persist/devtools/immer/subscribeWithSelector,
- bisa digunakan sebagai vanilla store tanpa React,
- mudah dites karena store bisa dibuat sebagai object/function biasa.

import { create } from 'zustand';

type SidebarState = {
  collapsed: boolean;
  toggle: () => void;
  setCollapsed: (collapsed: boolean) => void;
};

export const useSidebarStore = create<SidebarState>((set) => ({
  collapsed: false,
  toggle: () => set((state) => ({ collapsed: !state.collapsed })),
  setCollapsed: (collapsed) => set({ collapsed }),
}));

function SidebarButton() {
  const collapsed = useSidebarStore((state) => state.collapsed);
  const toggle = useSidebarStore((state) => state.toggle);

  return (
    <button onClick={toggle}>
      {collapsed ? 'Expand' : 'Collapse'}
    </button>
  );
}

Subscribe ke field/action yang dipakai.
Jangan subscribe ke seluruh state kecuali component memang butuh seluruh state.

// Anti-pattern untuk component besar
const store = useSidebarStore();

const collapsed = useSidebarStore((s) => s.collapsed);
const toggle = useSidebarStore((s) => s.toggle);

1. Singleton store
   - module-level store
   - satu instance untuk seluruh app/browser tab
   - cocok untuk app shell state

2. Scoped store
   - instance dibuat per page/subtree/request
   - disediakan lewat Context
   - cocok untuk multi-instance feature, SSR, test isolation

export const useCommandPaletteStore = create<CommandPaletteState>((set) => ({
  open: false,
  openPalette: () => set({ open: true }),
  closePalette: () => set({ open: false }),
}));

import { createContext, useContext, useRef } from 'react';
import { createStore, useStore } from 'zustand';

type DraftState = {
  title: string;
  setTitle: (title: string) => void;
};

function createDraftStore(initialTitle: string) {
  return createStore<DraftState>((set) => ({
    title: initialTitle,
    setTitle: (title) => set({ title }),
  }));
}

type DraftStore = ReturnType<typeof createDraftStore>;

const DraftStoreContext = createContext<DraftStore | null>(null);

export function DraftProvider({
  initialTitle,
  children,
}: {
  initialTitle: string;
  children: React.ReactNode;
}) {
  const storeRef = useRef<DraftStore | null>(null);

  if (storeRef.current === null) {
    storeRef.current = createDraftStore(initialTitle);
  }

  return (
    <DraftStoreContext.Provider value={storeRef.current}>
      {children}
    </DraftStoreContext.Provider>
  );
}

export function useDraftSelector<T>(selector: (state: DraftState) => T): T {
  const store = useContext(DraftStoreContext);

  if (!store) {
    throw new Error('useDraftSelector must be used inside <DraftProvider>.');
  }

  return useStore(store, selector);
}

- satu page bisa punya banyak instance feature yang sama,
- store perlu initial props berbeda,
- SSR/request isolation penting,
- test perlu isolated store,
- state harus reset saat subtree remount,
- global singleton berisiko bocor lintas user/session.

store/
  invoice-review.store.ts
  invoice-review.selectors.ts
  invoice-review.types.ts
  invoice-review.test.ts

type InvoiceReviewState = {
  selectedInvoiceIds: string[];
  panel: 'none' | 'details' | 'comments' | 'history';
  sort: { field: 'createdAt' | 'amount'; direction: 'asc' | 'desc' };

  selectOne: (id: string) => void;
  clearSelection: () => void;
  openPanel: (panel: InvoiceReviewState['panel']) => void;
  setSort: (sort: InvoiceReviewState['sort']) => void;
};

export const useInvoiceReviewStore = create<InvoiceReviewState>((set) => ({
  selectedInvoiceIds: [],
  panel: 'none',
  sort: { field: 'createdAt', direction: 'desc' },

  selectOne: (id) =>
    set((state) => ({
      selectedInvoiceIds: state.selectedInvoiceIds.includes(id)
        ? state.selectedInvoiceIds
        : [...state.selectedInvoiceIds, id],
    })),

  clearSelection: () => set({ selectedInvoiceIds: [] }),

  openPanel: (panel) => set({ panel }),

  setSort: (sort) => set({ sort }),
}));

export const selectSelectedInvoiceIds = (state: InvoiceReviewState) =>
  state.selectedInvoiceIds;

export const selectSelectedCount = (state: InvoiceReviewState) =>
  state.selectedInvoiceIds.length;

export const selectIsInvoiceSelected = (id: string) =>
  (state: InvoiceReviewState) => state.selectedInvoiceIds.includes(id);

function SelectionBadge() {
  const count = useInvoiceReviewStore(selectSelectedCount);
  return <span>{count} selected</span>;
}

function InvoiceRow({ id }: { id: string }) {
  const selected = useInvoiceReviewStore(selectIsInvoiceSelected(id));
  const selectOne = useInvoiceReviewStore((s) => s.selectOne);

  return (
    <button aria-pressed={selected} onClick={() => selectOne(id)}>
      {id}
    </button>
  );
}

type Store = {
  selectedIds: string[];
  setSelectedIds: (ids: string[]) => void;
};

setSelectedIds(['unknown-id', 'duplicate-id', 'duplicate-id']);

type Store = {
  selectedIds: string[];
  select: (id: string) => void;
  deselect: (id: string) => void;
  toggle: (id: string) => void;
  clear: () => void;
};

const useSelectionStore = create<Store>((set, get) => ({
  selectedIds: [],

  select: (id) =>
    set((state) => {
      if (state.selectedIds.includes(id)) return state;
      return { selectedIds: [...state.selectedIds, id] };
    }),

  deselect: (id) =>
    set((state) => ({
      selectedIds: state.selectedIds.filter((x) => x !== id),
    })),

  toggle: (id) => {
    const { selectedIds, select, deselect } = get();
    if (selectedIds.includes(id)) deselect(id);
    else select(id);
  },

  clear: () => set({ selectedIds: [] }),
}));

Public action harus menjaga invariant.
Component hanya mengirim intent.
Store memutuskan transisi.

type SelectionSlice = {
  selectedIds: string[];
  toggleSelected: (id: string) => void;
  clearSelection: () => void;
};

type PanelSlice = {
  panel: 'none' | 'details' | 'comments';
  openPanel: (panel: PanelSlice['panel']) => void;
  closePanel: () => void;
};

type InvoiceUiStore = SelectionSlice & PanelSlice;

import type { StateCreator } from 'zustand';

const createSelectionSlice: StateCreator<InvoiceUiStore, [], [], SelectionSlice> =
  (set) => ({
    selectedIds: [],
    toggleSelected: (id) =>
      set((state) => ({
        selectedIds: state.selectedIds.includes(id)
          ? state.selectedIds.filter((x) => x !== id)
          : [...state.selectedIds, id],
      })),
    clearSelection: () => set({ selectedIds: [] }),
  });

const createPanelSlice: StateCreator<InvoiceUiStore, [], [], PanelSlice> =
  (set) => ({
    panel: 'none',
    openPanel: (panel) => set({ panel }),
    closePanel: () => set({ panel: 'none' }),
  });

export const useInvoiceUiStore = create<InvoiceUiStore>()((...args) => ({
  ...createSelectionSlice(...args),
  ...createPanelSlice(...args),
}));

Slice boleh berkoordinasi dengan slice lain, tetapi jangan membuat dependency graph yang tidak terlihat.
Jika transisi melibatkan beberapa slice, pertimbangkan satu action orchestration eksplisit di root store.

type InvoiceUiStore = SelectionSlice & PanelSlice & {
  resetWorkspace: () => void;
};

export const useInvoiceUiStore = create<InvoiceUiStore>()((set, get, api) => ({
  ...createSelectionSlice(set, get, api),
  ...createPanelSlice(set, get, api),

  resetWorkspace: () =>
    set({
      selectedIds: [],
      panel: 'none',
    }),
}));

const selectedCount = useInvoiceUiStore((s) => s.selectedIds.length);

const { selectedIds, panel, sort, filters } = useInvoiceUiStore();

const value = useInvoiceUiStore((s) => ({
  count: s.selectedIds.length,
  panel: s.panel,
}));

import { shallow } from 'zustand/shallow';

const value = useInvoiceUiStore(
  (s) => ({
    count: s.selectedIds.length,
    panel: s.panel,
  }),
  shallow
);

const count = useInvoiceUiStore((s) => s.selectedIds.length);
const panel = useInvoiceUiStore((s) => s.panel);

set((state) => {
  state.selectedIds.push(id);
  return state;
});

set((state) => ({
  selectedIds: [...state.selectedIds, id],
}));

set((state) => ({
  entities: {
    ...state.entities,
    [id]: {
      ...state.entities[id],
      status: 'approved',
    },
  },
}));

import { immer } from 'zustand/middleware/immer';

export const useInvoiceStore = create<InvoiceStore>()(
  immer((set) => ({
    entities: {},
    approve: (id) =>
      set((state) => {
        state.entities[id].status = 'approved';
      }),
  }))
);

Immer memudahkan update nested.
Immer bukan izin untuk membuat state shape buruk.
Jika nested update terlalu sering, evaluasi normalisasi state.

- data bisa basi,
- schema bisa berubah,
- user bisa logout,
- storage bisa corrupt,
- hydration bisa berbeda dari server render,
- sensitive data bisa bocor,
- multi-tab bisa diverge.

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

type PreferencesStore = {
  density: 'comfortable' | 'compact';
  setDensity: (density: PreferencesStore['density']) => void;
};

export const usePreferencesStore = create<PreferencesStore>()(
  persist(
    (set) => ({
      density: 'comfortable',
      setDensity: (density) => set({ density }),
    }),
    {
      name: 'preferences:v1',
      storage: createJSONStorage(() => localStorage),
      partialize: (state) => ({ density: state.density }),
      version: 1,
    }
  )
);

partialize: (state) => ({
  density: state.density,
  sidebarCollapsed: state.sidebarCollapsed,
})

- access token tanpa threat model,
- server cache mentah tanpa invalidation,
- permission decision sebagai otoritas,
- volatile loading/error state,
- function/action,
- data besar tanpa quota strategy,
- temporary optimistic state tanpa reconciliation.

persist(
  (set) => ({
    density: 'comfortable',
    sidebar: { collapsed: false },
    setDensity: (density) => set({ density }),
  }),
  {
    name: 'preferences',
    version: 2,
    migrate: (persisted, version) => {
      if (version === 1) {
        const old = persisted as { compactMode?: boolean };
        return {
          density: old.compactMode ? 'compact' : 'comfortable',
          sidebar: { collapsed: false },
        };
      }
      return persisted as PreferencesStore;
    },
  }
);

Persisted state harus dianggap input tidak tepercaya.
Validasi, versi, migrasikan, dan punya fallback reset.

import { devtools } from 'zustand/middleware';

export const useInvoiceUiStore = create<InvoiceUiStore>()(
  devtools(
    (set) => ({
      selectedIds: [],
      toggleSelected: (id) =>
        set(
          (state) => ({
            selectedIds: state.selectedIds.includes(id)
              ? state.selectedIds.filter((x) => x !== id)
              : [...state.selectedIds, id],
          }),
          false,
          'selection/toggleSelected'
        ),
    }),
    { name: 'InvoiceUiStore' }
  )
);

Good action names:
- selection/toggleSelected
- panel/openDetails
- filters/apply
- workspace/reset

Bad action names:
- set
- update
- change
- doStuff

import { subscribeWithSelector } from 'zustand/middleware';

const useInvoiceStore = create<InvoiceUiStore>()(
  subscribeWithSelector((set) => ({
    selectedIds: [],
    toggleSelected: (id) =>
      set((state) => ({
        selectedIds: state.selectedIds.includes(id)
          ? state.selectedIds.filter((x) => x !== id)
          : [...state.selectedIds, id],
      })),
  }))
);

const unsubscribe = useInvoiceStore.subscribe(
  (state) => state.selectedIds.length,
  (count, previousCount) => {
    console.log({ count, previousCount });
  }
);

Jika subscribe dilakukan di module scope, pastikan memang global sepanjang app.
Jika subscribe dilakukan karena component hidup, lakukan di effect dan cleanup.

function SelectionAnalyticsBridge() {
  useEffect(() => {
    return useInvoiceStore.subscribe(
      (state) => state.selectedIds.length,
      (count) => analytics.track('selection_count_changed', { count })
    );
  }, []);

  return null;
}

subscribe tanpa cleanup = memory leak.
subscribe yang dispatch lagi tanpa guard = event loop/cycle.
subscribe untuk derivasi state = kemungkinan duplikasi source of truth.

type UserStore = {
  user: User | null;
  loading: boolean;
  error: string | null;
  loadUser: (id: string) => Promise<void>;
};

const useUserStore = create<UserStore>((set) => ({
  user: null,
  loading: false,
  error: null,

  loadUser: async (id) => {
    set({ loading: true, error: null });

    try {
      const user = await api.getUser(id);
      set({ user, loading: false });
    } catch (error) {
      set({ error: 'Failed to load user', loading: false });
    }
  },
}));

- no built-in staleTime/cacheTime,
- no automatic deduplication,
- no query key semantics,
- no retry policy by default,
- no background refetch,
- no mutation invalidation model,
- harder SSR dehydration/hydration story.

- TanStack Query,
- RTK Query,
- framework loader/cache,
- React Server Components/data layer sesuai framework.

- selected entity IDs,
- UI filters draft sebelum commit ke URL/query,
- active panel for entity detail,
- optimistic client-only queue dengan reconciliation eksplisit,
- command state yang mengarahkan mutation ke query layer.

function ApproveButton({ invoiceId }: { invoiceId: string }) {
  const closePanel = useInvoiceUiStore((s) => s.closePanel);
  const mutation = useApproveInvoiceMutation();

  return (
    <button
      onClick={async () => {
        await mutation.mutateAsync({ invoiceId });
        closePanel();
      }}
    >
      Approve
    </button>
  );
}

type SearchStore = {
  query: string;
  result: SearchResult | null;
  status: 'idle' | 'loading' | 'success' | 'error';
  requestId: string | null;
  search: (query: string) => Promise<void>;
};

const useSearchStore = create<SearchStore>((set, get) => ({
  query: '',
  result: null,
  status: 'idle',
  requestId: null,

  search: async (query) => {
    const requestId = crypto.randomUUID();

    set({ query, status: 'loading', requestId });

    try {
      const result = await api.search(query);

      if (get().requestId !== requestId) {
        return;
      }

      set({ result, status: 'success' });
    } catch {
      if (get().requestId !== requestId) {
        return;
      }

      set({ status: 'error' });
    }
  },
}));

Only latest request may commit result.

User membuka Case A.
Panel comments terbuka.
User pindah ke Case B.
Panel comments masih terbuka karena store global tidak reset.

function CasePage({ caseId }: { caseId: string }) {
  const reset = useCaseUiStore((s) => s.reset);

  useEffect(() => {
    reset({ caseId });
  }, [caseId, reset]);

  return <CaseWorkspace caseId={caseId} />;
}

<CaseUiProvider caseId={caseId}>
  <CaseWorkspace />
</CaseUiProvider>

<CaseUiProvider key={caseId} caseId={caseId}>
  <CaseWorkspace />
</CaseUiProvider>

For request-scoped SSR state, create store per request/render boundary.
Do not share mutable singleton store across users on the server.

function createAppStore(initialState: Partial<AppStoreState>) {
  return createStore<AppStoreState>()((set) => ({
    sidebarCollapsed: initialState.sidebarCollapsed ?? false,
    setSidebarCollapsed: (sidebarCollapsed) => set({ sidebarCollapsed }),
  }));
}

- server renders default collapsed=false,
- client persisted storage hydrates collapsed=true,
- first client paint differs from server output.

- only use persisted preference after mounted,
- gate non-critical UI until hydration,
- serialize initial server snapshot,
- choose CSS that tolerates initial default,
- keep persisted state out of critical SSR markup when possible.

type LoadStatus =
  | { tag: 'idle' }
  | { tag: 'loading'; requestId: string }
  | { tag: 'success' }
  | { tag: 'error'; message: string };

type CaseUiState = {
  activeTab: 'summary' | 'evidence' | 'timeline';
  selectedEvidenceIds: string[];
  loadStatus: LoadStatus;
};

type CaseUiActions = {
  openTab: (tab: CaseUiState['activeTab']) => void;
  toggleEvidence: (id: string) => void;
  clearEvidenceSelection: () => void;
};

type CaseUiStore = CaseUiState & CaseUiActions;

- discriminated union for lifecycle state,
- branded IDs for domain IDs if useful,
- command names over generic setters,
- selectors typed from store state,
- store factory for test/SSR.

- `Record<string, any>`,
- raw backend DTO as editable UI state,
- optional fields that create ambiguous illegal states,
- action payloads that accept arbitrary partial state.

import { createStore } from 'zustand/vanilla';

function createSelectionStore() {
  return createStore<SelectionStore>()((set) => ({
    selectedIds: [],
    toggle: (id) =>
      set((state) => ({
        selectedIds: state.selectedIds.includes(id)
          ? state.selectedIds.filter((x) => x !== id)
          : [...state.selectedIds, id],
      })),
  }));
}

test('toggle selects and deselects id', () => {
  const store = createSelectionStore();

  store.getState().toggle('inv-1');
  expect(store.getState().selectedIds).toEqual(['inv-1']);

  store.getState().toggle('inv-1');
  expect(store.getState().selectedIds).toEqual([]);
});

test('notifies selected count changes', () => {
  const store = createSelectionStore();
  const listener = vi.fn();

  const unsubscribe = store.subscribe(listener);

  store.getState().toggle('a');
  store.getState().toggle('b');

  expect(listener).toHaveBeenCalledTimes(2);

  unsubscribe();
});

render(
  <SelectionProvider store={createSelectionStore()}>
    <SelectionBadge />
  </SelectionProvider>
);

Test store transitions at store level.
Test component rendering at integration boundary.
Do not assert implementation detail of Zustand internals.

const useAuditStore = create<AuditStore>()(
  devtools((set) => ({
    status: { tag: 'idle' },
    submitStarted: (requestId) =>
      set({ status: { tag: 'submitting', requestId } }, false, 'submit/started'),
    submitSucceeded: (requestId) =>
      set({ status: { tag: 'success', requestId } }, false, 'submit/succeeded'),
  }))
);

1. Which component reads the state?
2. Which action changed it?
3. Was the store singleton or scoped?
4. Did selector return stable value?
5. Did a persisted value override initial value?
6. Did async response commit after newer request?
7. Did component subscribe to too much state?
8. Was state reset when route/entity changed?

Use Zustand when you need external-store ergonomics without Redux governance weight.
Use Redux Toolkit when the cost of freedom is higher than boilerplate cost.

features/invoice-review/
  invoice-review.store.ts
  invoice-review.selectors.ts
  invoice-review.types.ts
  InvoiceReviewPage.tsx

features/case-workspace/
  state/
    case-workspace.store.ts
    case-workspace.selectors.ts
    case-workspace.actions.ts
    case-workspace.types.ts
    create-case-workspace-store.ts
  components/
    CaseWorkspaceShell.tsx
    EvidencePanel.tsx
    TimelinePanel.tsx

stores/
  app.store.ts   // 2000 lines of everything

useAppStore contains user, theme, modal, filters, entities, server data, loading flags, permissions, toasts, page state.

No ownership decision.

Split by lifecycle and authority, not by convenience.

const state = useAppStore();

const collapsed = useAppStore((s) => s.sidebarCollapsed);

const vm = useStore((s) => ({ a: s.a, b: s.b }));

const vm = useStore((s) => ({ a: s.a, b: s.b }), shallow);

Manual fetch, manual loading flags, manual stale cache, manual invalidation everywhere.

Move server-owned data to server-state cache.
Keep Zustand for UI state around it.

App crashes after deploy because old localStorage shape no longer matches code.

Version, migrate, validate, reset fallback.

User A sees User B state in SSR environment.

Create store per request. Inject through provider.

Slow response from old query overwrites faster response from new query.

Request identity guard or use server-state cache.

useState
→ useReducer
→ reducer + Context
→ mini external store
→ Zustand
→ Redux Toolkit / state machine / server-state cache depending on problem

[ ] State ini bukan server-owned cache.
[ ] Store lifetime jelas: singleton/scoped/per-request.
[ ] Store punya owner feature yang jelas.
[ ] Component memakai selectors, bukan root store snapshot.
[ ] Action menjaga invariant, bukan raw setter liar.
[ ] State shape meminimalkan duplicated source of truth.
[ ] Persistence hanya untuk field yang memang perlu.
[ ] Persisted state punya version/migration jika schema bisa berubah.
[ ] Sensitive data tidak dipersist tanpa threat model.
[ ] Async action punya request identity guard atau dipindah ke query layer.
[ ] Store reset saat route/entity/session berubah.
[ ] Tests mencakup transition penting.
[ ] Devtools/action names cukup jelas untuk debugging.

- activeTab: summary | evidence | timeline | decision
- selectedEvidenceIds
- rightPanel: none | evidence-detail | comment-thread
- density: comfortable | compact, persisted
- command: openEvidence(id), closePanel(), toggleEvidence(id), resetWorkspace(caseId)
- selector: selectedEvidenceCount, isEvidenceSelected(id), canBulkReview
- request/lifetime: reset ketika caseId berubah

- Jangan simpan detail evidence dari server di Zustand.
- Simpan hanya selected IDs dan UI panel state.
- Buat test untuk toggle, reset, dan selector.
- Gunakan persist hanya untuk density.

- Buat scoped store provider per caseId.
- Tambahkan devtools action name.
- Tambahkan subscribeWithSelector untuk analytics selected count.

- pilih state yang memang client-owned,
- desain action sebagai command/intention,
- gunakan selector granular,
- kontrol lifetime,
- jangan jadikan server cache,
- persist hanya yang aman dan perlu,
- buat store factory untuk scoped/test/SSR,
- ukur performance sebelum membuat abstraksi berlebihan.