Zustand 実践メモ

1. Zustand は何を解決するのか

Zustand の中心は「React コンポーネントの外にストアを置き、コンポーネントはセレクタで必要な部分だけ購読する」という形である。 create が返すものは React フックであり、同時に getState, setState, subscribe, getInitialState を持つストアでもある。

「グローバル状態を全部入れる場所」ではなく、「複数のコンポーネントから同じ可変状態を参照し、更新と購読を明示的に管理したい場所」と考える方が事故が少ない。 React の局所状態、URL、サーバーデータのキャッシュ、フォーム管理まで Zustand に集める必要はない。

2. 基本的な使用方法

まずは create でストアを作り、コンポーネントではセレクタで必要な値や更新関数だけを取り出す。 Provider で囲む必要はなく、作ったフックを import して呼ぶだけで使える。

npm install zustand

# pnpm の場合
pnpm add zustand

import { create } from 'zustand'

type CounterState = {
  count: number
  increase: () => void
  reset: () => void
}

export const useCounterStore = create<CounterState>()((set) => ({
  count: 0,
  increase: () => set((state) => ({ count: state.count + 1 })),
  reset: () => set({ count: 0 }),
}))

React コンポーネントでは、ストア全体ではなく表示や操作に必要なものを選んで読む。 更新関数も同じフックから取り出して、イベントハンドラで呼べばよい。

function Counter() {
  const count = useCounterStore((state) => state.count)
  const increase = useCounterStore((state) => state.increase)
  const reset = useCounterStore((state) => state.reset)

  return (
    <div>
      <p>count: {count}</p>
      <button onClick={increase}>+1</button>
      <button onClick={reset}>Reset</button>
    </div>
  )
}

コンポーネント外から現在値を読む場合は getState、外部イベントを購読する場合は subscribe を使える。 ただし、画面に表示する値はフックで購読し、外部購読では解除関数を管理する。

const currentCount = useCounterStore.getState().count

const unsubscribe = useCounterStore.subscribe((state, prevState) => {
  if (state.count !== prevState.count) {
    console.log('count changed:', state.count)
  }
})

unsubscribe()

3. コア実装から分かること

Zustand の素のストアは概念的には次の構造である。 実装では Set に購読関数を持ち、setState が新しい状態を作って購読関数に現在の状態と直前の状態を渡す。

type StoreApi<T> = {
  setState: {
    (partial: T | Partial<T> | ((state: T) => T | Partial<T>), replace?: false): void
    (state: T | ((state: T) => T), replace: true): void
  }
  getState: () => T
  getInitialState: () => T
  subscribe: (listener: (state: T, prevState: T) => void) => () => void
}

重要なのは setState の既定動作である。 replace を明示しない通常更新では、次の値がオブジェクトの場合に Object.assign({}, state, nextState) 相当の浅いマージになる。 深いマージではないため、入れ子のオブジェクトは自分で不変更新する必要がある。

type AuthState = {
  user: { id: string; name: string } | null
  status: 'anonymous' | 'loading' | 'authenticated'
  actions: {
    setUser: (user: AuthState['user']) => void
    rename: (name: string) => void
  }
}

const useAuthStore = create<AuthState>()((set) => ({
  user: null,
  status: 'anonymous',
  actions: {
    setUser: (user) => set({ user, status: user ? 'authenticated' : 'anonymous' }),
    rename: (name) =>
      set((state) => ({
        user: state.user ? { ...state.user, name } : null,
      })),
  },
}))

4. セレクタと再レンダリング

React 側の useStore は内部で React.useSyncExternalStore を使い、selector(api.getState()) の結果をスナップショットとして扱う。 セレクタの戻り値が変わったと判断されると、コンポーネントは再レンダリングされる。 v5 の標準 create では比較関数を直接渡せないため、戻り値は基本的に Object.is で比較されるものとして考える。

4-1. 小さいセレクタを基本にする

const userName = useAuthStore((state) => state.user?.name)
const status = useAuthStore((state) => state.status)
const rename = useAuthStore((state) => state.actions.rename)

プリミティブ値や安定した関数参照を個別に取るセレクタは扱いやすい。 ストア初期化時に作った更新関数は、その関数自体を差し替えない限り同じ参照を保つ。

4-2. オブジェクトや配列を毎回作るセレクタは注意する

// 更新のたびに新しいオブジェクトを返す
const view = useAuthStore((state) => ({
  name: state.user?.name,
  status: state.status,
}))

このセレクタは呼ばれるたびに新しいオブジェクトを返す。 値の中身が同じでも参照は異なるため、不要な再レンダリングや v5 での不安定なスナップショット問題につながり得る。 複数値をまとめたい場合は useShallow を使う。

import { useShallow } from 'zustand/react/shallow'

const view = useAuthStore(
  useShallow((state) => ({
    name: state.user?.name,
    status: state.status,
  })),
)

v5 移行ガイドでは、セレクタが新しい参照を返す場合に無限ループになり得る例も示されている。 代替関数をセレクタ内で毎回作るようなコードも同じ問題を持つ。

const NOOP = () => {}

const onSubmit = useFormStore((state) => state.onSubmit ?? NOOP)

5. ストアの形と更新関数の置き方

Zustand は reducer を強制しない。 実務では状態と更新関数を同じストアに置き、コンポーネントからは更新関数を呼ぶだけにする形が読みやすい。 ただし更新関数をどこに置くかは、セレクタの安定性と永続化の対象に影響する。

type Todo = { id: string; title: string; done: boolean }

type TodoStore = {
  todos: Record<string, Todo>
  order: string[]
  actions: {
    add: (title: string) => void
    toggle: (id: string) => void
    remove: (id: string) => void
  }
}

export const useTodoStore = create<TodoStore>()((set) => ({
  todos: {},
  order: [],
  actions: {
    add: (title) => {
      const id = crypto.randomUUID()
      set((state) => ({
        todos: { ...state.todos, [id]: { id, title, done: false } },
        order: [...state.order, id],
      }))
    },
    toggle: (id) =>
      set((state) => {
        const todo = state.todos[id]
        if (!todo) return {}
        return {
          todos: { ...state.todos, [id]: { ...todo, done: !todo.done } },
        }
      }),
    remove: (id) =>
      set((state) => {
        const { [id]: _removed, ...todos } = state.todos
        return { todos, order: state.order.filter((todoId) => todoId !== id) }
      }),
  },
}))

上の例では更新関数を actions にまとめている。 これは必須ではないが、persist の partialize で状態だけを保存しやすく、コンポーネント側でも useTodoStore((s) => s.actions.add) のように選びやすい。

5-1. スライス分割は実装分割であってストア分散ではない

公式ドキュメントの slices pattern は、複数の作成関数を展開して一つの結合済みストアを作る方法である。 ミドルウェアは個別スライスではなく、結合したストアに適用するのが公式の注意点である。

const createUserSlice = (set) => ({
  user: null,
  setUser: (user) => set({ user }),
})

const createProjectSlice = (set, get) => ({
  projects: {},
  clearUserProjects: () => {
    const user = get().user
    if (user) set({ projects: {} })
  },
})

export const useAppStore = create((...args) => ({
  ...createUserSlice(...args),
  ...createProjectSlice(...args),
}))

6. 型付け

TypeScript では create<State>()((set, get) => ...) の二段呼び出し形式を使うのが基本である。

type SessionState = {
  token: string | null
  expiresAt: number | null
  actions: {
    setSession: (token: string, expiresAt: number) => void
    clear: () => void
  }
}

export const useSessionStore = create<SessionState>()((set) => ({
  token: null,
  expiresAt: null,
  actions: {
    setSession: (token, expiresAt) => set({ token, expiresAt }),
    clear: () => set({ token: null, expiresAt: null }),
  },
}))

v5 では setState の replace: true に対する型が厳しくなっている。 replace: true はルートの状態を完全に置き換える指定なので、部分オブジェクトを渡す用途には使わない。

// 通常の浅いマージ
useSessionStore.setState({ token: 'new-token' })

// 完全置換。actions も含めて完全な状態が必要
useSessionStore.setState(
  {
    token: null,
    expiresAt: null,
    actions: useSessionStore.getState().actions,
  },
  true,
)

7. ミドルウェアは必要なものだけ足す

Zustand のミドルウェアはストア作成関数を包む関数である。 代表的には persist, devtools, immer, subscribeWithSelector, redux がある。 どれも便利だが、ストアの意味を変えるため、導入理由を明確にする。

7-1. persist は保存対象を絞る

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

export const useSettingsStore = create<SettingsStore>()(
  persist(
    (set) => ({
      theme: 'system',
      draftSearchQuery: '',
      actions: {
        setTheme: (theme) => set({ theme }),
        setDraftSearchQuery: (draftSearchQuery) => set({ draftSearchQuery }),
      },
    }),
    {
      name: 'settings-v1',
      storage: createJSONStorage(() => localStorage),
      partialize: (state) => ({ theme: state.theme }),
      version: 1,
    },
  ),
)

persist は既定で localStorage を使う。 一時的な入力値、通信由来の古くなりやすいデータ、認可上慎重に扱うべき値を雑に保存しない。 公式ドキュメントでは skipHydration が SSR 用の選択肢として説明されている。

8. React での境界設計

8-1. コンポーネントでは読み取りを細くする

コンポーネントで useStore() とセレクタなしに呼ぶと、そのコンポーネントはストア全体を購読する。 画面が大きくなるほど、関係ない更新で再レンダリングされる範囲が広がる。

// 避けたい: ストアのどこが変わっても再レンダリング候補になる
const state = useTodoStore()

// よい: このコンポーネントが必要なものだけ読む
const todo = useTodoStore((state) => state.todos[id])
const toggle = useTodoStore((state) => state.actions.toggle)

8-2. イベント処理内での非購読の読み取り

getState はコンポーネント外やイベント処理で現在値を読む逃げ道として使える。 ただし描画中に使う値なら、フック経由で購読する。

function SaveButton() {
  const save = async () => {
    const { todos } = useTodoStore.getState()
    await saveTodos(Object.values(todos))
  }

  return <button onClick={save}>Save</button>
}

8-3. React Context と素のストア

Zustand は通常、提供元コンポーネントを必要としない。ただし、ストアを props で初期化したい場合、テストで差し替えたい場合、Next.js 等でリクエストごとにストアを分けたい場合は Context が有効である。 公式ドキュメントではフックそのものを Context に入れるのではなく、createStore で作った素のストアと useStore(store, selector) を組み合わせる方法が示されている。

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

const CounterStoreContext = createContext<ReturnType<typeof createCounterStore> | null>(null)

function CounterStoreProvider({ children }: { children: React.ReactNode }) {
  const [store] = useState(() => createCounterStore({ count: 0 }))
  return (
    <CounterStoreContext.Provider value={store}>
      {children}
    </CounterStoreContext.Provider>
  )
}

function useCounter<T>(selector: (state: CounterStore) => T): T {
  const store = useContext(CounterStoreContext)
  if (!store) throw new Error('CounterStoreProvider is missing')
  return useStore(store, selector)
}

9. SSR / Next.js での注意点

Zustand のストアはモジュール状態になり得る。 クライアントだけで動く単一ページアプリならそれが利点になるが、サーバーが複数リクエストを処理する環境では、リクエスト間で状態を共有しない設計が必要である。 公式の Next.js ガイドも「ストアはリクエストごとに作る」「React Server Components はストアを読んだり書いたりしない」と説明している。

ハイドレーションではサーバーとクライアントの初期出力が一致する必要がある。 localStorage を読む persist ストア、現在時刻、乱数、ブラウザ専用 API に依存する値は、初期描画に混ぜると不一致を作りやすい。 SSR 対応が必要なストアは、初期値を明示的に渡す、クライアントのマウント後に復元する、またはそもそもサーバー描画の表示条件から外す。

10. 実務でのベストプラクティス

1. ストアに入れる前に、React の局所状態、URL、サーバーデータのキャッシュ、フォーム管理のどれかで足りないか確認する。
2. コンポーネントではセレクタを必ず書く。ストア全体を読むコンポーネントを増やさない。
3. セレクタはプリミティブ値、安定参照、または useShallow で安定化したオブジェクトや配列を返す。
4. 更新関数はストアに置き、コンポーネントからは更新関数を呼ぶ。更新処理をコンポーネントに散らさない。
5. ルートの状態は浅い構造を優先する。深いオブジェクトを頻繁に更新するなら正規化や immer を検討する。
6. persist は保存対象を partialize で絞り、形式変更に備えて version と migrate を設計する。
7. SSR ではモジュール上のグローバルストアをユーザー別、リクエスト別の状態に使わない。ストア作成関数と Context で境界を作る。
8. React 外の購読は必ず解除関数を管理する。長寿命の処理で購読を放置するとリークになる。
9. replace: true は完全置換として扱う。部分更新のつもりで使わない。
10. ストアを巨大化させすぎない。スライス分割は「一つのストアを保ったまま実装を分ける」ために使う。

11. よくある失敗

12. Zustand を使わない方がよい場面

Zustand は小さいが、万能な状態置き場ではない。 通信結果のキャッシュ、ページング、再試行、古さ判定、更新後の再取得が中心ならサーバーデータ用ライブラリの領域である。 複雑なフォーム検証とフィールド単位の変更管理が中心ならフォームライブラリの領域である。 URL と共有される絞り込みやタブは URLSearchParams の方がよい場合が多い。

Zustand がよく合うのは、画面横断のクライアント状態、複数コンポーネント間で共有する編集・セッション・作業領域の状態、React 外のイベントからも更新される状態、提供元コンポーネントの階層を増やしたくない単一ページアプリの状態である。 逆に「全部 Zustand に寄せる」設計は、責務が見えにくくなる。

Appendix. API・実装チートシート

ミドルウェア早見表

参考

• Zustand docs
• Zustand on GitHub