apollo-client

Apollo Client 4.x ガイド

Apollo Client は、GraphQL を使ってローカルデータとリモートデータの両方を管理できる、JavaScript 用の包括的な状態管理ライブラリです。バージョン 4.x では、キャッシュの改善、TypeScript のサポート強化、React 19 との互換性が実現されています。

統合ガイド

アプリケーションのセットアップに合った統合ガイドを選択してください。

• クライアントサイドアプリ - SSR を使用しないクライアントサイドの React アプリケーション向け（Vite、Create React App など）
• Next.js App Router - React Server Components を使う App Router 対応の Next.js アプリケーション向け
• React Router Framework Mode - ストリーミング SSR に対応した React Router 7 アプリケーション向け
• TanStack Start - モダンなルーティングを備えた TanStack Start アプリケーション向け

各ガイドには、インストール手順、設定、および環境に合わせて最適化されたフレームワーク固有のパターンが含まれています。

クイックリファレンス

基本的なクエリ

import { gql } from "@apollo/client";
import { useQuery } from "@apollo/client/react";

const GET_USER = gql`
  query GetUser($id: ID!) {
    user(id: $id) {
      id
      name
    }
  }
`;

function UserProfile({ userId }: { userId: string }) {
  const { loading, error, data, dataState } = useQuery(GET_USER, {
    variables: { id: userId },
  });

  if (loading) return <p>Loading...</p>;
  if (error) return <p>Error: {error.message}</p>;

  // TypeScript note: for stricter type narrowing, you can also check `dataState === "complete"` before accessing data
  return <div>{data?.user.name}</div>;
}

基本的なミューテーション

import { gql } from "@apollo/client";
import { useMutation } from "@apollo/client/react";

const CREATE_USER = gql`
  mutation CreateUser($input: CreateUserInput!) {
    createUser(input: $input) {
      id
      name
    }
  }
`;

function CreateUserForm() {
  const [createUser, { loading, error }] = useMutation(CREATE_USER);

  const handleSubmit = async (name: string) => {
    await createUser({ variables: { input: { name } } });
  };

  return <button onClick={() => handleSubmit("John")}>Create User</button>;
}

Suspense クエリ

import { Suspense } from "react";
import { useSuspenseQuery } from "@apollo/client/react";

function UserProfile({ userId }: { userId: string }) {
  const { data } = useSuspenseQuery(GET_USER, {
    variables: { id: userId },
  });

  return <div>{data.user.name}</div>;
}

function App() {
  return (
    <Suspense fallback={<p>Loading user...</p>}>
      <UserProfile userId="1" />
    </Suspense>
  );
}

リファレンスファイル

特定のトピックに関する詳細なドキュメントです。

• TypeScript コード生成 - 型安全な操作のための GraphQL Code Generator のセットアップ
• クエリ - useQuery、useLazyQuery、ポーリング、再フェッチ
• Suspense フック - useSuspenseQuery、useBackgroundQuery、useReadQuery、useLoadableQuery
• ミューテーション - useMutation、楽観的 UI、キャッシュ更新
• フラグメント - フラグメントのコロケーション、useFragment、useSuspenseFragment、データマスキング
• キャッシュ - InMemoryCache、typePolicies、キャッシュ操作
• 状態管理 - リアクティブ変数、ローカル状態
• エラー処理 - エラーポリシー、エラーリンク、再試行
• トラブルシューティング - よくある問題と解決方法

重要なルール

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

• 通常、各ページには、コロケーションされたフラグメントを組み合わせたクエリを 1 つだけ配置します。 ページコンポーネント以外のすべてのコンポーネントでは、useFragment または useSuspenseFragment を使用します。スクロールせずに見える範囲より下にある読み込みの遅いフィールドを後からストリーミングし、ページの読み込みを妨げないようにするには、@defer を使用します。
• フラグメントはコロケーションのためのものであり、再利用のためのものではありません。 各フラグメントは、共通フィールドを共有するために複数のコンポーネント間で使い回すのではなく、特定のコンポーネントが必要とするデータを正確に記述する必要があります。フラグメントのコロケーションとデータマスキングの詳細については、フラグメントのリファレンスを参照してください。
• Suspense を使用しないフック（useQuery、useLazyQuery）では、UI で loading 状態と error 状態を必ず処理してください。Suspense フック（useSuspenseQuery、useBackgroundQuery）を使用する場合、React は <Suspense> 境界とエラー境界を通じてこれらを処理します。
• クエリごとのキャッシュ動作を制御するには、fetchPolicy を使用します。
• 関数やオプションのドキュメントを参照するには、TypeScript の型サーバーを使用します（Apollo Client には詳細な docblock が用意されています）。

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

• スキーマで許可されている場合、ミューテーションの戻り値には、キャッシュの更新に必要なすべての情報を含める必要があります。 手動での更新も再フェッチも必要ありません。
• ミューテーションのレスポンスが不十分な場合は、キャッシュの手動操作と再フェッチを慎重に比較検討してください。手動更新ではサーバー側のロジックを反映し損ねるリスクがあります。必要に応じて、粒度を調整した再フェッチを伴う楽観的更新を検討してください。
• UI でエラーを適切に処理してください。
• refetchQueries の使用は最小限に抑えてください（キャッシュによる自動更新を優先します）。

キャッシュのベストプラクティス

• id フィールドを持たない型には keyFields を設定します
• 識別子を含まず、関連するフィールドを親の下にまとめる型には、keyFields: false を設定して正規化を無効にします
• ページネーションや計算フィールドには typePolicies を使用します
• 問題のデバッグに備えて、キャッシュの正規化を理解しておきます
• 新しいアプリケーションではすべて、データマスキングを有効にします。これにより、コンポーネントが所有していないフラグメントデータにアクセスできなくなり、適切なデータ境界を維持するとともに、過剰な再レンダリングを防げます

パフォーマンス

• 適切なフィールド選択により、過剰なデータ取得を避けます
• ユースケースごとに適切な fetchPolicy を設定します
• 遅延されたクエリ部分を段階的に配信するには @defer を使用し、リストフィールドをストリーミングするには @stream を使用します（@stream は Apollo Client 4.1 以降で利用可能です）
• 最新のアプリケーションでは、より適切な読み込み状態の処理とコードの簡潔さのために、Suspense フック（useSuspenseQuery、useBackgroundQuery）を優先します

基本原則

• 必ず Apollo Client 4.x のパターンを使用します（v3 以前ではありません）
• 必ず ApolloProvider でアプリをラップします
• Suspense 非対応のフックを使用する場合は、必ず読み込み状態とエラー状態を処理します
• 最新のアプリケーションでは、より優れた開発者体験のために、Suspense フック（useSuspenseQuery、useBackgroundQuery）を優先します
• Apollo Client を React の state に保存してはいけません（モジュールレベルまたはコンテキストを使用します）
• 読み取り中心のデータには cache-first を、リアルタイムデータには network-only を優先します
• GraphQL の型安全性を高めるために TypeScript を使用します
• クエリ全体を再取得するのではなく、適切なキャッシュ更新を実装します
• Apollo Client の問題を共同でデバッグするときは、Apollo DevTools を確認するよう、あなたを支援する人に提案します