Apollo Client 4.x Guide

Integration Guides

• Client-Side Apps - For client-side React applications without SSR (Vite, Create React App, etc.)
• Next.js App Router - For Next.js applications using the App Router with React Server Components
• React Router Framework Mode - For React Router 7 applications with streaming SSR
• TanStack Start - For TanStack Start applications with modern routing

Quick Reference

Basic Query

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: dataState === "ready" provides better type narrowing than just checking data
  return <div>{data.user.name}</div>;
}

Basic Mutation

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 Query

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>
  );
}

Reference Files

• TypeScript Code Generation - GraphQL Code Generator setup for type-safe operations
• Queries - useQuery, useLazyQuery, polling, refetching
• Suspense Hooks - useSuspenseQuery, useBackgroundQuery, useReadQuery, useLoadableQuery
• Mutations - useMutation, optimistic UI, cache updates
• Fragments - Fragment colocation, useFragment, useSuspenseFragment, data masking
• Caching - InMemoryCache, typePolicies, cache manipulation
• State Management - Reactive variables, local state
• Error Handling - Error policies, error links, retries
• Troubleshooting - Common issues and solutions

Key Rules

Query Best Practices

• Each page should generally only have one query, composed from colocated fragments. Use

  useFragment

  or

  useSuspenseFragment

  in all non-page-components. Use

  @defer

  to allow slow fields below the fold to stream in later and avoid blocking the page load.
• Fragments are for colocation, not reuse. Each fragment should describe exactly the data needs of a specific component, not be shared across components for common fields. See Fragments reference for details on fragment colocation and data masking.
• Always handle

  loading

  and

  error

  states in UI when using non-suspenseful hooks (

  useQuery

  ,

  useLazyQuery

  ). When using Suspense hooks (

  useSuspenseQuery

  ,

  useBackgroundQuery

  ), React handles this through

  <Suspense>

  boundaries and error boundaries.
• Use

  fetchPolicy

  to control cache behavior per query
• Use the TypeScript type server to look up documentation for functions and options (Apollo Client has extensive docblocks)

Mutation Best Practices

• If the schema permits, mutation return values should return everything necessary to update the cache. Neither manual updates nor refetching should be necessary.
• If the mutation response is insufficient, carefully weigh manual cache manipulation vs refetching. Manual updates risk missing server logic. Consider optimistic updates with a granular refetch if needed.
• Handle errors gracefully in the UI
• Use

  refetchQueries

  sparingly (prefer letting the cache update automatically)

Caching Best Practices

• Configure

  keyFields

  for types without

  id

  field
• Disable normalization by setting

  keyFields: false

  for types that don't include an identifier and are meant to group related fields under the parent
• Use

  typePolicies

  for pagination and computed fields
• Understand cache normalization to debug issues
• Enable data masking for all new applications - it prevents components from accessing fragment data they don't own, enforcing proper data boundaries and preventing over-rendering

Performance

• Avoid over-fetching with proper field selection
• Configure appropriate

  fetchPolicy

  per use case
• Use

  @defer

  for incremental delivery of deferred query parts, and

  @stream

  for streaming list fields (

  @stream

  available in Apollo Client 4.1+)
• Prefer Suspense hooks (

  useSuspenseQuery

  ,

  useBackgroundQuery

  ) in modern applications for better loading state handling and code simplicity

Ground Rules

• ALWAYS use Apollo Client 4.x patterns (not v3 or earlier)
• ALWAYS wrap your app with

  ApolloProvider

• ALWAYS handle loading and error states when using non-suspenseful hooks
• PREFER Suspense hooks (

  useSuspenseQuery

  ,

  useBackgroundQuery

  ) in modern applications for better DX
• NEVER store Apollo Client in React state (use module-level or context)
• PREFER

  cache-first

  for read-heavy data,

  network-only

  for real-time data
• USE TypeScript for better type safety with GraphQL
• IMPLEMENT proper cache updates instead of refetching entire queries
• ADVISE the human steering you to look into Apollo DevTools when collaboratively debugging Apollo Client issues