zustand-patterns

Zustand のパターン

Zustand 5.x によるモダンな状態管理：軽量で、TypeScript を第一に考え、ボイラープレートは不要です。

概要

• Redux のような複雑さを伴わないグローバル状態
• props のバケツリレーをせずにコンポーネント間で状態を共有
• localStorage/sessionStorage による状態の永続化
• セレクターによる計算済み／派生状態
• ミドルウェア（ロギング、devtools、永続化）が必要な状態

上流ドキュメントの対象範囲（再記述しないでください）

仕組みについては Zustand 自身のドキュメントを参照してください。このスキルには、その内容に加えて OrchestKit 固有の差分のみが含まれており、references/ork-delta.md、rules/ ファイル、チェックリストに記載されています。

トピック	公式ドキュメント
基本的なストア、create<State>()()、アクション、非同期アクション	https://github.com/pmndrs/zustand/blob/main/docs/reference/apis/create.md
スライスパターン（ストアの分割と結合）	https://github.com/pmndrs/zustand/blob/main/docs/learn/guides/slices-pattern.md
スライスとミドルウェアのミューテータタプルの型付け	https://github.com/pmndrs/zustand/blob/main/docs/learn/guides/advanced-typescript.md
Immer ミドルウェア（ドラフトの変更）	https://github.com/pmndrs/zustand/blob/main/docs/reference/middlewares/immer.md
persist：partialize、version、migrate、onRehydrateStorage、ストレージアダプター	https://github.com/pmndrs/zustand/blob/main/docs/reference/middlewares/persist.md
devtools：アクション名、enabled、serialize、trace	https://github.com/pmndrs/zustand/blob/main/docs/reference/middlewares/devtools.md
subscribeWithSelector と React を使わないサブスクリプション	https://github.com/pmndrs/zustand/blob/main/docs/reference/middlewares/subscribe-with-selector.md
セレクターと再レンダリング制御のための useShallow	https://github.com/pmndrs/zustand/blob/main/docs/learn/guides/prevent-rerenders-with-use-shallow.md
v4 から v5 への移行（createWithEqualityFn、React 18 以上）	https://github.com/pmndrs/zustand/blob/main/docs/reference/migrations/migrating-to-v5.md
SSR とハイドレーション	https://github.com/pmndrs/zustand/blob/main/docs/learn/guides/ssr-and-hydration.md
ストアのテストとリセット	https://github.com/pmndrs/zustand/blob/main/docs/learn/guides/testing.md
サーバー状態の管理（Zustand ではなく TanStack Query を使用）	https://tanstack.com/query/latest/docs/framework/react/guides/does-this-replace-client-state

クイックリファレンス

// ✅ Create typed store with double-call pattern
const useStore = create<State>()((set, get) => ({ ... }));

// ✅ Use selectors for all state access
const count = useStore((s) => s.count);

// ✅ Use useShallow for multiple values (Zustand 5.x)
const { a, b } = useStore(useShallow((s) => ({ a: s.a, b: s.b })));

// ✅ Middleware order: immer → subscribeWithSelector → devtools → persist
create(persist(devtools(immer((set) => ({ ... })))))

// ❌ Never destructure entire store
const store = useStore(); // Re-renders on ANY change

// ❌ Never store server state (use TanStack Query instead)
const useStore = create((set) => ({ users: [], fetchUsers: async () => ... }));

重要な判断事項

判断項目	選択肢 A	選択肢 B	推奨
状態の構造	単一ストア	複数のストア	単一ストア内のスライス - スライス間のアクセスが容易です
ネストした更新	スプレッド演算子	Immer ミドルウェア	Immer：深くネストした状態（3 階層以上）に適しています
永続化	手動の localStorage	persist ミドルウェア	partialize を使用する persist ミドルウェア
複数の値	複数のセレクター	useShallow	関連する値が 2～5 個の場合は useShallow
サーバー状態	Zustand	TanStack Query	TanStack Query - Zustand はクライアント側のみの状態に使用します
DevTools	常に有効	条件付き	条件付き - enabled: process.env.NODE_ENV === 'development'

アンチパターンと統合

禁止されているパターン（ストアの分割代入、派生状態、サーバー状態、直接変更）と React Query との統合方法について説明します。

アンチパターンの例と TanStack Query との分離パターンについては、Load Read("references/anti-patterns-and-integration.md") を読み込んでください。

関連スキル

• react-server-components-framework - Zustand を使用する際の RSC ハイドレーションに関する考慮事項
• サーバー状態：https://tanstack.com/query/latest/docs/framework/react/guides/does-this-replace-client-state
• フォーム状態：https://react-hook-form.com/docs/useform

機能の詳細

store-creation

キーワード: zustand, create, store, typescript, state 解決する課題: 適切な TypeScript 推論を利用して、型安全な Zustand ストアを設定する

slices-pattern

キーワード: slices, modular, split, combine, StateCreator 解決する課題: 大規模なストアを、保守しやすいドメイン固有のスライスに整理する

middleware-stack

キーワード：immer、persist、devtools、middleware、compose 解決する課題：イミュータビリティ、永続化、デバッグのために、ミドルウェアを正しい順序で組み合わせること

selector-optimization

キーワード：selector、useShallow、再レンダリング、パフォーマンス、メモ化 解決する課題：適切なセレクターパターンを使って、不要な再レンダリングを防ぐこと

persistence-migration

キーワード：persist、localStorage、sessionStorage、移行、バージョン 解決する課題：バージョン間のスキーマ移行に対応して状態を永続化すること

参考資料

Read("references/<file>") で必要に応じて読み込みます：

ファイル	内容
ork-delta.md	OrchestKit 固有のルール：修正後の zustand/shallow ラベル、v5 の最低要件、シークレットの取り扱い、段階的なスライスの型付け
anti-patterns-and-integration.md	禁止されているパターンと React Query の統合

その他のリソース：

• 読み込み：Read("scripts/store-template.ts") - 本番環境向けストアテンプレート
• 読み込み：Read("checklists/zustand-checklist.md") - 実装チェックリスト