Apollo Client 4.x Guide

Apollo Client is a comprehensive state management library for JavaScript that enables you to manage both local and remote data with GraphQL. Version 4.x brings improved caching, better TypeScript support, and React 19 compatibility.

Quick Start Step 1: Install npm install @apollo/client graphql rxjs

For TypeScript type generation (recommended):

npm install -D @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-operations @graphql-codegen/typed-document-node

See the GraphQL Code Generator documentation for the recommended configuration.

Step 2: Create Client import { ApolloClient, InMemoryCache, HttpLink } from '@apollo/client'; import { setContext } from '@apollo/client/link/context';

const httpLink = new HttpLink({ uri: 'https://your-graphql-endpoint.com/graphql', });

// Use SetContextLink for auth headers to update dynamically per request const authLink = setContext((_, { headers }) => { const token = localStorage.getItem('token'); return { headers: { ...headers, authorization: token ? Bearer ${token} : '', }, }; });

const client = new ApolloClient({ link: authLink.concat(httpLink), cache: new InMemoryCache(), });

Step 3: Setup Provider import { ApolloProvider } from '@apollo/client'; import App from './App';

function Root() { return ( ); }

Step 4: Execute Query import { gql } from '@apollo/client'; import { useQuery } from '@apollo/client/react';

const GET_USERS = gqlquery GetUsers { users { id name email } };

function UserList() { const { loading, error, data } = useQuery(GET_USERS);

if (loading) return

; if (error) return

Error: {error.message}

;

return (

{user.name}

); }

Basic Query Usage Using Variables const GET_USER = gqlquery GetUser($id: ID!) { user(id: $id) { id name email } };

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

if (loading) return

; if (error) return

Error: {error.message}

;

return

{data.user.name}

; }

Note for TypeScript users: Use dataState for more robust type safety and better type narrowing in Apollo Client 4.x.

TypeScript Integration interface User { id: string; name: string; email: string; }

interface GetUserData { user: User; }

interface GetUserVariables { id: string; }

const { data } = useQuery(GET_USER, { variables: { id: userId }, });

// data.user is typed as User

Basic Mutation Usage import { gql, TypedDocumentNode } from '@apollo/client'; import { useMutation } from '@apollo/client/react';

interface CreateUserMutation { createUser: { id: string; name: string; email: string; }; }

interface CreateUserMutationVariables { input: { name: string; email: string; }; }

const CREATE_USER: TypedDocumentNode = gqlmutation CreateUser($input: CreateUserInput!) { createUser(input: $input) { id name email } };

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

return (

); }

Client Configuration Options const client = new ApolloClient({ // Required: The cache implementation cache: new InMemoryCache({ typePolicies: { Query: { fields: { // Field-level cache configuration }, }, }, }),

// Network layer link: new HttpLink({ uri: '/graphql' }),

// Default options for queries/mutations defaultOptions: { watchQuery: { fetchPolicy: 'cache-and-network', errorPolicy: 'all', }, query: { fetchPolicy: 'network-only', errorPolicy: 'all', }, mutate: { errorPolicy: 'all', }, },

// Enable Apollo DevTools (development only) connectToDevTools: process.env.NODE_ENV === 'development',

// Custom name for this client instance name: 'web-client', version: '1.0.0', });

Reference Files

Detailed documentation for specific topics:

Queries - useQuery, useLazyQuery, polling, refetching Mutations - useMutation, optimistic UI, cache updates 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 In most applications, use one query hook per page, and use fragment-reading hooks (useFragment, useSuspenseFragment) with component-colocated fragments and data masking for the rest Always handle loading and error states in UI (in non-suspenseful applications) Use fetchPolicy to control cache behavior per query Colocate queries with components that use them Use fragments to share fields between queries 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 include everything necessary to update the cache automatically Weigh cache updates vs refetching: manual updates risk missing server logic, but refetching may be inefficient Consider optimistic updates with granular refetches if mutation response is insufficient Handle errors gracefully in the UI Use refetchQueries sparingly (prefer cache updates) 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

apollo-client

安装