TanStack Query ベストプラクティス

TanStack Query（旧 React Query）、TypeScript、React 開発の専門家です。TanStack Query はキャッシング、バックグラウンド更新、古いデータの処理をゼロコンフィギュレーションで扱います。

コア原則

• すべてのサーバーステート管理とデータ取得に TanStack Query を使用する
• サーバーデータに対する useEffect と useState の使用を最小化し、TanStack Query の組み込みステート管理を優先する
• ユーザーフレンドリーなメッセージによる適切なエラー処理を実装する
• TypeScript を使用してクエリレスポンスに完全な型安全性を実現する

プロジェクト構造

src/
  api/
    client.ts             # API クライアント設定
    endpoints/
      users.ts            # ユーザー関連の API 呼び出し
      posts.ts            # ポスト関連の API 呼び出し
  hooks/
    queries/
      useUsers.ts         # ユーザークエリフック
      usePosts.ts         # ポストクエリフック
    mutations/
      useCreateUser.ts    # ユーザーミューテーションフック
  providers/
    QueryProvider.tsx     # クエリクライアントプロバイダーセットアップ
  types/
    api.ts                # API レスポンス型

セットアップと設定

クエリクライアント設定

// providers/QueryProvider.tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 60 * 5, // 5分
      gcTime: 1000 * 60 * 30,   // 30分（旧 cacheTime）
      retry: 3,
      refetchOnWindowFocus: true,
      refetchOnReconnect: true,
    },
    mutations: {
      retry: 1,
    },
  },
});

export function QueryProvider({ children }: { children: React.ReactNode }) {
  return (
    <QueryClientProvider client={queryClient}>
      {children}
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  );
}

クエリのベストプラクティス

1. クエリキーの構成

効率的なキャッシュ管理のために、一貫した階層的なクエリキーを使用します：

// クエリキーファクトリーパターン
export const userKeys = {
  all: ['users'] as const,
  lists: () => [...userKeys.all, 'list'] as const,
  list: (filters: UserFilters) => [...userKeys.lists(), filters] as const,
  details: () => [...userKeys.all, 'detail'] as const,
  detail: (id: string) => [...userKeys.details(), id] as const,
};

2. カスタムクエリフック

再利用可能で型指定されたクエリフックを作成します：

// hooks/queries/useUser.ts
import { useQuery, UseQueryOptions } from '@tanstack/react-query';
import { userKeys } from '@/api/queryKeys';
import { getUser, User } from '@/api/endpoints/users';

export function useUser(
  userId: string,
  options?: Omit<UseQueryOptions<User, Error>, 'queryKey' | 'queryFn'>
) {
  return useQuery({
    queryKey: userKeys.detail(userId),
    queryFn: () => getUser(userId),
    enabled: !!userId,
    ...options,
  });
}

3. 依存クエリ

他のデータに依存するクエリを処理します：

function useUserPosts(userId: string) {
  const { data: user } = useUser(userId);

  return useQuery({
    queryKey: ['posts', { userId }],
    queryFn: () => fetchUserPosts(userId),
    enabled: !!user, // ユーザーデータが利用可能な場合のみ実行
  });
}

4. 並列クエリ

複数のリソースを同時に取得します：

import { useQueries } from '@tanstack/react-query';

function useMultipleUsers(userIds: string[]) {
  return useQueries({
    queries: userIds.map((id) => ({
      queryKey: userKeys.detail(id),
      queryFn: () => getUser(id),
    })),
  });
}

ミューテーションのベストプラクティス

1. 楽観的更新

ミューテーション実行中に即座のフィードバックを提供します：

import { useMutation, useQueryClient } from '@tanstack/react-query';

function useUpdateUser() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: updateUser,
    onMutate: async (newUser) => {
      // 発信中の再フェッチをキャンセル
      await queryClient.cancelQueries({ queryKey: userKeys.detail(newUser.id) });

      // 前の値をスナップショット
      const previousUser = queryClient.getQueryData(userKeys.detail(newUser.id));

      // 楽観的に更新
      queryClient.setQueryData(userKeys.detail(newUser.id), newUser);

      return { previousUser };
    },
    onError: (err, newUser, context) => {
      // エラー時にロールバック
      queryClient.setQueryData(
        userKeys.detail(newUser.id),
        context?.previousUser
      );
    },
    onSettled: (data, error, variables) => {
      // エラーまたは成功後に再フェッチ
      queryClient.invalidateQueries({ queryKey: userKeys.detail(variables.id) });
    },
  });
}

2. キャッシュ無効化

ミューテーション後に関連クエリを適切に無効化します：

function useDeleteUser() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: deleteUser,
    onSuccess: () => {
      // すべてのユーザー関連クエリを無効化
      queryClient.invalidateQueries({ queryKey: userKeys.all });
    },
  });
}

エラーハンドリング

1. グローバルエラーハンドラー

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      throwOnError: false,
    },
    mutations: {
      onError: (error) => {
        // グローバルエラーハンドリング（例：トースト通知）
        toast.error(error.message);
      },
    },
  },
});

2. コンポーネントレベルのエラーハンドリング

function UserProfile({ userId }: { userId: string }) {
  const { data, error, isLoading, isError } = useUser(userId);

  if (isLoading) return <Skeleton />;
  if (isError) return <ErrorMessage error={error} />;

  return <UserCard user={data} />;
}

3. Suspense を使用したエラーバウンダリー

import { ErrorBoundary } from 'react-error-boundary';
import { Suspense } from 'react';

function App() {
  return (
    <ErrorBoundary fallback={<ErrorFallback />}>
      <Suspense fallback={<Loading />}>
        <UserProfile userId="123" />
      </Suspense>
    </ErrorBoundary>
  );
}

パフォーマンス最適化

1. データの選択と変換

必要なデータのみをサブスクライブします：

function useUserName(userId: string) {
  return useUser(userId, {
    select: (user) => user.name,
  });
}

2. プリフェッチング

データが必要になる前にプリフェッチします：

function UserList() {
  const queryClient = useQueryClient();

  const prefetchUser = (userId: string) => {
    queryClient.prefetchQuery({
      queryKey: userKeys.detail(userId),
      queryFn: () => getUser(userId),
      staleTime: 1000 * 60 * 5,
    });
  };

  return (
    <ul>
      {users.map((user) => (
        <li key={user.id} onMouseEnter={() => prefetchUser(user.id)}>
          {user.name}
        </li>
      ))}
    </ul>
  );
}

3. インフィニットクエリ

ページネーションデータを効率的に処理します：

import { useInfiniteQuery } from '@tanstack/react-query';

function useInfinitePosts() {
  return useInfiniteQuery({
    queryKey: ['posts'],
    queryFn: ({ pageParam }) => fetchPosts(pageParam),
    initialPageParam: 0,
    getNextPageParam: (lastPage) => lastPage.nextCursor,
    getPreviousPageParam: (firstPage) => firstPage.prevCursor,
  });
}

キー規約

1. 機能ベースの構成：機能固有のディレクトリ内にクエリフックをグループ化する
2. 一貫したクエリキー：型安全で構成されたキーのためにファクトリー関数を使用する
3. 型安全性：すべての API レスポンスに対して TypeScript インターフェースを定義する
4. DevTools：開発時に必ず React Query DevTools を含める
5. 深くネストされたクエリを避ける：可能な限りクエリ構造をフラット化する
6. 必要なデータのみを取得：API パラメータを使用してレスポンスサイズを制限する
7. ローディングとエラー状態を処理：常に適切な UI フィードバックを提供する

避けるべきアンチパターン

• データ取得に useEffect を使用しない - クエリを代わりに使用する
• サーバーステートをローカル状態（useState）に保存しない
• ローディング状態とエラー状態の処理を忘れない
• キャッシュ再利用を妨げるほど具体的なクエリキーを作成しない
• ミューテーション後のキャッシュ無効化をスキップしない
• 条件付きクエリの enabled オプションを無視しない