Zustand State Management

When to Use

Use this skill when creating or modifying state that crosses component boundaries. Covers store creation, tab-based state isolation, slice composition, selector performance, middleware (devtools, persist, immer), and multi-view synchronization patterns.

---

1. Store Creation

Basic Store with TypeScript

import { create } from "zustand";

interface CounterStore {
  count: number;
  increment: () => void;
  decrement: () => void;
  reset: () => void;
}

const useCounterStore = create<CounterStore>((set) => ({
  count: 0,
  increment: () => set((state) => ({ count: state.count + 1 })),
  decrement: () => set((state) => ({ count: state.count - 1 })),
  reset: () => set({ count: 0 }),
}));

Reading State Without Subscribing

Use get() inside actions to read state without causing re-renders:

const useStore = create<Store>((set, get) => ({
  nodes: [],
  addNodeIfNotExists: (node) => {
    const existing = get().nodes.find((n) => n.id === node.id);
    if (!existing) {
      set((state) => ({ nodes: [...state.nodes, node] }));
    }
  },
}));

Reading State Outside Components

// Get current state snapshot (no subscription)
const currentNodes = useStore.getState().nodes;

// Call actions outside React
useStore.getState().addNode(newNode);

// Subscribe to changes outside React
const unsub = useStore.subscribe((state) => console.log(state.nodes));

---

2. Tab-Based State Isolation

Critical pattern for multi-tab applications. Each tab maintains isolated state within a single store using a Record<tabId, TabState> structure.

Store Structure

interface Tab {
  id: string;
  type: "investigation" | "case" | "alert";
  title: string;
  metadata: Record<string, unknown>;
  createdAt: Date;
  lastAccessedAt: Date;
}

interface TabState {
  nodes: Node[];
  relationships: Relationship[];
  hiddenNodeIds: Set<string>;
  removedNodeIds: Set<string>;
  selectedNodeIds: Set<string>;
  isDirty: boolean;
}

interface InvestigationStore {
  tabs: Tab[];
  activeTabId: string | null;
  tabStates: Record<string, TabState>;

  addTab: (tab: Tab, initialState?: Partial<TabState>) => void;
  closeTab: (tabId: string) => void;
  switchTab: (tabId: string) => void;
  updateTabState: (tabId: string, updates: Partial<TabState>) => void;
  getActiveTabState: () => TabState | null;
}

Implementation

import { create } from "zustand";

const defaultTabState: TabState = {
  nodes: [],
  relationships: [],
  hiddenNodeIds: new Set(),
  removedNodeIds: new Set(),
  selectedNodeIds: new Set(),
  isDirty: false,
};

const useInvestigationStore = create<InvestigationStore>((set, get) => ({
  tabs: [],
  activeTabId: null,
  tabStates: {},

  addTab: (tab, initialState = {}) =>
    set((state) => ({
      tabs: [...state.tabs, tab],
      activeTabId: tab.id,
      tabStates: {
        ...state.tabStates,
        [tab.id]: { ...defaultTabState, ...initialState },
      },
    })),

  closeTab: (tabId) =>
    set((state) => {
      const newTabs = state.tabs.filter((t) => t.id !== tabId);
      // CRITICAL: Remove tab state to prevent memory leaks
      const { [tabId]: _removed, ...remainingTabStates } = state.tabStates;
      const newActiveTabId =
        state.activeTabId === tabId
          ? newTabs.length > 0
            ? newTabs[newTabs.length - 1].id
            : null
          : state.activeTabId;

      return {
        tabs: newTabs,
        tabStates: remainingTabStates,
        activeTabId: newActiveTabId,
      };
    }),

  switchTab: (tabId) =>
    set((state) => ({
      tabs: state.tabs.map((tab) =>
        tab.id === tabId ? { ...tab, lastAccessedAt: new Date() } : tab,
      ),
      activeTabId: tabId,
    })),

  updateTabState: (tabId, updates) =>
    set((state) => ({
      tabStates: {
        ...state.tabStates,
        [tabId]: {
          ...state.tabStates[tabId],
          ...updates,
          isDirty: true,
        },
      },
    })),

  getActiveTabState: () => {
    const state = get();
    return state.activeTabId
      ? (state.tabStates[state.activeTabId] ?? null)
      : null;
  },
}));

Accessing Tab State in Components

// Always scope state access to the active tab
const GraphCanvas = () => {
  const activeTabId = useInvestigationStore((state) => state.activeTabId);
  const nodes = useInvestigationStore((state) =>
    state.activeTabId ? state.tabStates[state.activeTabId]?.nodes ?? [] : []
  );
  const hiddenNodeIds = useInvestigationStore((state) =>
    state.activeTabId
      ? state.tabStates[state.activeTabId]?.hiddenNodeIds ?? new Set()
      : new Set()
  );

  if (!activeTabId) return <EmptyState />;

  const handleNodeClick = (nodeId: string) => {
    useInvestigationStore.getState().updateTabState(activeTabId, {
      selectedNodeIds: new Set([nodeId]),
    });
  };

  return <NVL nodes={nodes.filter((n) => !hiddenNodeIds.has(n.id))} />;
};

Custom Hook for Tab State

const useTabState = () => {
  const activeTabId = useInvestigationStore((state) => state.activeTabId);
  const tabState = useInvestigationStore((state) =>
    state.activeTabId ? (state.tabStates[state.activeTabId] ?? null) : null,
  );
  return { activeTabId, tabState };
};

---

3. Selectors and Performance

Fine-Grained Selectors

// ✅ Only re-renders when nodes change for the active tab
const nodes = useStore((state) =>
  state.activeTabId ? (state.tabStates[state.activeTabId]?.nodes ?? []) : [],
);

// ✅ Computed value — only re-renders when inputs change
const visibleNodeCount = useStore((state) => {
  const tabState = state.activeTabId
    ? state.tabStates[state.activeTabId]
    : null;
  if (!tabState) return 0;
  return tabState.nodes.filter((n) => !tabState.removedNodeIds.has(n.id))
    .length;
});

// ❌ Subscribes to entire store — re-renders on ANY change
const store = useStore();

// ❌ Subscribes to all tab states — re-renders when ANY tab changes
const tabStates = useStore((state) => state.tabStates);

Shallow Equality for Object/Array Selectors

When a selector returns a new object or array reference each time, use useShallow to compare by shallow equality:

import { useShallow } from "zustand/react/shallow";

// Without useShallow: re-renders on every store update (new object each time)
// With useShallow: only re-renders when the values inside change
const { nodes, relationships } = useStore(
  useShallow((state) => {
    const tabState = state.activeTabId
      ? state.tabStates[state.activeTabId]
      : null;
    return {
      nodes: tabState?.nodes ?? [],
      relationships: tabState?.relationships ?? [],
    };
  }),
);

Batch Updates

// ❌ Three separate set() calls = three re-renders
set({ nodes: newNodes });
set({ relationships: newRelationships });
set({ isDirty: true });

// ✅ Single set() call = one re-render
set({
  nodes: newNodes,
  relationships: newRelationships,
  isDirty: true,
});

---

4. Multi-View Synchronization

When multiple views (table, graph, timeline) share state, one Zustand action updates the store and all subscribed components re-render automatically.

Synchronization Flow

User clicks node in Graph
    → Store action: updateTabState(tabId, { selectedNodeIds: new Set([nodeId]) })
        → Graph re-renders (highlights selected node)
        → Table re-renders (highlights selected row)
        → Timeline re-renders (highlights related events)

Example: Hide Node (Propagates to All Views)

// Store action
hideNode: (tabId: string, nodeId: string) =>
  set((state) => ({
    tabStates: {
      ...state.tabStates,
      [tabId]: {
        ...state.tabStates[tabId],
        hiddenNodeIds: new Set([
          ...state.tabStates[tabId].hiddenNodeIds,
          nodeId,
        ]),
        isDirty: true,
      },
    },
  })),

// Graph component: filters out hidden nodes
const visibleNodes = nodes.filter((n) => !hiddenNodeIds.has(n.id));

// Table component: shows hidden nodes as dimmed
const rowClass = hiddenNodeIds.has(node.id) ? 'opacity-30' : '';

// Timeline component: excludes events for hidden nodes
const visibleEvents = events.filter((e) => !hiddenNodeIds.has(e.nodeId));

---

5. Middleware

DevTools

import { devtools } from "zustand/middleware";

const useStore = create<Store>()(
  devtools(
    (set, get) => ({
      // ... store implementation
    }),
    { name: "InvestigationStore" },
  ),
);

Immer (Mutable Draft Syntax)

Use immer for deeply nested updates (like tab state):

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

const useStore = create<Store>()(
  immer((set) => ({
    tabs: [],
    activeTabId: null,
    tabStates: {},

    hideNode: (tabId, nodeId) =>
      set((state) => {
        state.tabStates[tabId].hiddenNodeIds.add(nodeId);
        state.tabStates[tabId].isDirty = true;
      }),
  })),
);

Persist (Selective)

Persist tab metadata but not full state (too large):

import { persist } from "zustand/middleware";

const useStore = create<Store>()(
  persist(
    (set, get) => ({
      // ... store implementation
    }),
    {
      name: "finsight-investigation-storage",
      partialize: (state) => ({
        tabs: state.tabs,
        activeTabId: state.activeTabId,
        // Do NOT persist tabStates — too large, reconstruct on load
      }),
      onRehydrateStorage: () => (state) => {
        if (state) {
          // Reinitialize empty tab states for persisted tabs
          const tabStates: Record<string, TabState> = {};
          state.tabs.forEach((tab) => {
            tabStates[tab.id] = { ...defaultTabState };
          });
          state.tabStates = tabStates;
        }
      },
    },
  ),
);

Combining Middleware

Order matters — outermost wraps first:

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

const useStore = create<Store>()(
  devtools(
    persist(
      immer((set, get) => ({
        // ... store implementation
      })),
      {
        name: "storage-key",
        partialize: (state) => ({
          /* ... */
        }),
      },
    ),
    { name: "StoreName" },
  ),
);

---

6. Store Organization

Separate stores by domain. Don't create one massive store.

src/stores/
├── investigation.ts    # Per-tab investigation state (graph, table, timeline)
├── timeline.ts         # Per-tab timeline/changelog entries
├── layout.ts           # UI layout state (panel positions, sidebar)
├── settings.ts         # Global user preferences
├── cases.ts            # Shared case list (cross-tab)
├── alerts.ts           # Shared alert list (cross-tab)
└── index.ts            # Re-export all stores

Per-tab stores (investigation, timeline): State keyed by tabId, cleaned up on tab close. Global stores (settings, layout): Single state shared across all tabs. Shared domain stores (cases, alerts): Cross-tab data that multiple tabs can subscribe to.

---

7. Testing Zustand Stores

Reset State Between Tests

import { describe, it, expect, beforeEach } from "vitest";
import useInvestigationStore from "./investigation";

describe("InvestigationStore", () => {
  beforeEach(() => {
    // Reset store to initial state before each test
    useInvestigationStore.setState({
      tabs: [],
      activeTabId: null,
      tabStates: {},
    });
  });

  it("should add a new tab with default state", () => {
    const tab = {
      id: "tab-1",
      type: "investigation" as const,
      title: "Test Investigation",
      metadata: {},
      createdAt: new Date(),
      lastAccessedAt: new Date(),
    };

    useInvestigationStore.getState().addTab(tab);

    const state = useInvestigationStore.getState();
    expect(state.tabs).toHaveLength(1);
    expect(state.activeTabId).toBe("tab-1");
    expect(state.tabStates["tab-1"]).toBeDefined();
    expect(state.tabStates["tab-1"].nodes).toEqual([]);
  });

  it("should clean up state when closing a tab", () => {
    const tab = {
      id: "tab-1",
      type: "investigation" as const,
      title: "Test",
      metadata: {},
      createdAt: new Date(),
      lastAccessedAt: new Date(),
    };

    useInvestigationStore.getState().addTab(tab);
    useInvestigationStore.getState().closeTab("tab-1");

    const state = useInvestigationStore.getState();
    expect(state.tabs).toHaveLength(0);
    expect(state.tabStates["tab-1"]).toBeUndefined();
    expect(state.activeTabId).toBeNull();
  });
});

---

Anti-Patterns

Anti-Pattern	Why It Fails	Fix
const store = useStore()	Subscribes to entire store — re-renders on every change	Use a selector: useStore((s) => s.nodes)
Creating stores inside components	New store on every render, loses all state	Create stores at module level or in a factory
Forgetting to remove tab state on close	Memory leak — closed tabs keep data in memory	Destructure out the tab: const { [tabId]: _, ...rest } = state.tabStates
set({ nodes: state.nodes.push(newNode) })	Mutating state directly — Zustand won't detect the change	Spread into new array: set({ nodes: [...state.nodes, newNode] }) or use immer
Subscribing to state.tabStates	Re-renders when ANY tab changes, not just the active tab	Select only the active tab: state.tabStates[state.activeTabId]
Multiple set() calls in one action	Each set() triggers a re-render	Combine into a single set() call
Storing derived state	Stale data if source changes and derived isn't updated	Compute derived values in selectors
Using Zustand when local state suffices	Unnecessary global state, extra complexity	Use useState for component-local UI state (open/closed, hover, input values)