Claude CodeでReact状態管理を設計する実践ガイド｜Zustand・Jotai・TanStack Query 5層モデル

## 状態管理

### 5層アーキテクチャ
- Server State: TanStack Query v5（APIデータはすべてここ。useStateに入れない）
- Global State: Zustand v5（認証・テーマ・通知）
- Atomic State: Jotai v2（フィルタ・選択状態・UIの細粒度共有）
- Local State: useState/useReducer（コンポーネント内完結）
- Form State: React Hook Form + Zod

### ディレクトリ構造
src/
  stores/          # Zustand ストア（auth.ts, ui.ts等）
  atoms/           # Jotai atoms（filters.ts, selection.ts等）
  hooks/queries/   # TanStack Query カスタムフック

### ルール
- APIデータは必ずTanStack Queryで管理（useStateに入れない）
- Zustandストアは機能単位で分割（auth, ui, notifications）
- Zustandセレクタは個別フィールドで購読（オブジェクト全体を取らない）
- グローバル状態に入れる前に「本当に複数コンポーネントで必要か」確認
- TanStack Queryのキーは配列形式で階層的に（["todos", "list", { filter }]）
- Recoilは使用しない（メンテナンスモード）
- Redux Toolkitは既存プロジェクトでのみ使用（新規はZustand）

認証ストアをZustand v5で作成してください。

要件:
- user, token, isAuthenticated を管理
- login/logoutアクション
- persistミドルウェアでlocalStorageに永続化（user/tokenのみ）
- immerミドルウェアでイミュータブル更新
- devtoolsミドルウェア（開発環境のみ）
- セレクタのベストプラクティスに従う

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

interface User {
  id: string;
  name: string;
  email: string;
  role: "admin" | "editor" | "viewer";
}

interface AuthStore {
  user: User | null;
  token: string | null;
  isAuthenticated: boolean;
  login: (email: string, password: string) => Promise<void>;
  logout: () => void;
}

export const useAuthStore = create<AuthStore>()(
  devtools(
    persist(
      immer((set) => ({
        user: null,
        token: null,
        isAuthenticated: false,

        login: async (email, password) => {
          const res = await fetch("/api/auth/login", {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({ email, password }),
          });
          if (!res.ok) throw new Error("認証に失敗しました");
          const { user, token } = await res.json();

          set((state) => {
            state.user = user;
            state.token = token;
            state.isAuthenticated = true;
          });
        },

        logout: () => {
          set((state) => {
            state.user = null;
            state.token = null;
            state.isAuthenticated = false;
          });
        },
      })),
      {
        name: "auth-store",
        partialize: (state) => ({ user: state.user, token: state.token }),
      }
    ),
    { name: "AuthStore", enabled: process.env.NODE_ENV === "development" }
  )
);

import { useShallow } from "zustand/shallow";

// NG: オブジェクト全体を購読（すべてのフィールド変更で再レンダリング）
const { user, isAuthenticated } = useAuthStore();

// OK: 個別セレクタ（必要な値だけ購読）
const user = useAuthStore((state) => state.user);
const isAuthenticated = useAuthStore((state) => state.isAuthenticated);

// OK: 複数値を浅い比較で購読（useShallow）
const { user, isAuthenticated } = useAuthStore(
  useShallow((state) => ({
    user: state.user,
    isAuthenticated: state.isAuthenticated,
  }))
);

// 派生値はセレクタ関数として定義（コンポーネント外）
const selectDisplayName = (state: AuthStore) =>
  state.user ? `${state.user.name}` : "ゲスト";

function UserGreeting() {
  const displayName = useAuthStore(selectDisplayName);
  return <p>こんにちは、{displayName}さん</p>;
}

import { atom } from "jotai";

// 基本atom
export const searchQueryAtom = atom("");
export const sortOrderAtom = atom<"asc" | "desc">("desc");
export const selectedCategoryAtom = atom<string | null>(null);

// derived atom（読み取り専用：他のatomから計算）
export const activeFilterCountAtom = atom((get) => {
  let count = 0;
  if (get(searchQueryAtom)) count++;
  if (get(selectedCategoryAtom)) count++;
  if (get(sortOrderAtom) !== "desc") count++;
  return count;
});

// writable derived atom（読み書き：リセット機能）
export const resetFiltersAtom = atom(null, (_get, set) => {
  set(searchQueryAtom, "");
  set(sortOrderAtom, "desc");
  set(selectedCategoryAtom, null);
});

import { useAtom, useAtomValue, useSetAtom } from "jotai";
import { searchQueryAtom, activeFilterCountAtom, resetFiltersAtom } from "@/atoms/filters";

function FilterBar() {
  const [query, setQuery] = useAtom(searchQueryAtom);
  const filterCount = useAtomValue(activeFilterCountAtom);
  const resetFilters = useSetAtom(resetFiltersAtom);

  return (
    <div>
      <input value={query} onChange={(e) => setQuery(e.target.value)} placeholder="検索..." />
      <span>アクティブフィルタ: {filterCount}</span>
      <button onClick={() => resetFilters()}>リセット</button>
    </div>
  );
}

import { useQuery, useMutation, useQueryClient, useSuspenseQuery } from "@tanstack/react-query";
import type { Todo, NewTodo } from "@/types";

// データ取得（キャッシュ5分、GC30分）
export function useTodos(filter?: string) {
  return useQuery({
    queryKey: ["todos", "list", { filter }],
    queryFn: () => api.getTodos({ filter }),
    staleTime: 5 * 60 * 1000,
    gcTime: 30 * 60 * 1000,  // v5: cacheTime → gcTime
  });
}

// Suspense版（data が undefined にならない）
export function useTodosSuspense(filter?: string) {
  return useSuspenseQuery({
    queryKey: ["todos", "list", { filter }],
    queryFn: () => api.getTodos({ filter }),
  });
}

// 楽観的更新付きミューテーション
export function useAddTodo() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: (newTodo: NewTodo) => api.addTodo(newTodo),

    onMutate: async (newTodo) => {
      await queryClient.cancelQueries({ queryKey: ["todos"] });
      const previous = queryClient.getQueryData<Todo[]>(["todos", "list"]);

      // 楽観的にUIを更新
      queryClient.setQueryData<Todo[]>(["todos", "list"], (old = []) => [
        ...old,
        { ...newTodo, id: crypto.randomUUID(), completed: false },
      ]);

      return { previous };
    },

    onError: (_err, _newTodo, context) => {
      // エラー時はロールバック
      if (context?.previous) {
        queryClient.setQueryData(["todos", "list"], context.previous);
      }
    },

    onSettled: () => {
      // 成功・失敗にかかわらずサーバーから再取得
      queryClient.invalidateQueries({ queryKey: ["todos"] });
    },
  });
}

import { useState } from "react";
import { useAtom, useAtomValue } from "jotai";
import { useAuthStore } from "@/stores/auth";
import { searchQueryAtom, selectedCategoryAtom, activeFilterCountAtom } from "@/atoms/filters";
import { useTodosSuspense, useAddTodo } from "@/hooks/queries/useTodos";

export function TodoPage() {
  // Layer 4: Global State（Zustand）
  const user = useAuthStore((s) => s.user);

  // Layer 3: Atomic State（Jotai）
  const [query] = useAtom(searchQueryAtom);
  const [category] = useAtom(selectedCategoryAtom);
  const filterCount = useAtomValue(activeFilterCountAtom);

  // Layer 5: Server State（TanStack Query）
  const { data: todos } = useTodosSuspense(query);
  const addTodo = useAddTodo();

  // Layer 2: Local State（useState）
  const [isFormOpen, setIsFormOpen] = useState(false);

  return (
    <div>
      <header>
        <span>{user?.name}さんのTodo</span>
        <span>フィルタ: {filterCount}</span>
      </header>
      <FilterBar />
      <TodoList todos={todos} />
      <button onClick={() => setIsFormOpen(true)}>追加</button>
      {isFormOpen && (
        <CreateTodoForm
          onSubmit={(data) => addTodo.mutate(data)}
          onClose={() => setIsFormOpen(false)}
        />
      )}
    </div>
  );
}