GraphQL Client Patterns with Apollo

Apollo Client provides powerful GraphQL capabilities for React applications. Here's how to use it effectively.

Setup and Configuration#

// lib/apollo.ts
import {
  ApolloClient,
  InMemoryCache,
  createHttpLink,
  from,
} from '@apollo/client';
import { setContext } from '@apollo/client/link/context';
import { onError } from '@apollo/client/link/error';

// HTTP link
const httpLink = createHttpLink({
  uri: process.env.NEXT_PUBLIC_GRAPHQL_URL,
});

// Auth link
const authLink = setContext((_, { headers }) => {
  const token = localStorage.getItem('token');
  return {
    headers: {
      ...headers,
      authorization: token ? `Bearer ${token}` : '',
    },
  };
});

// Error link
const errorLink = onError(({ graphQLErrors, networkError, operation }) => {
  if (graphQLErrors) {
    graphQLErrors.forEach(({ message, locations, path }) => {
      console.error(
        `[GraphQL error]: Message: ${message}, Location: ${locations}, Path: ${path}`
      );
    });
  }

  if (networkError) {
    console.error(`[Network error]: ${networkError}`);

    if ('statusCode' in networkError && networkError.statusCode === 401) {
      // Handle unauthorized
      localStorage.removeItem('token');
      window.location.href = '/login';
    }
  }
});

// Cache configuration
const cache = new InMemoryCache({
  typePolicies: {
    Query: {
      fields: {
        // Pagination
        posts: {
          keyArgs: ['filter'],
          merge(existing = [], incoming, { args }) {
            if (args?.offset === 0) {
              return incoming;
            }
            return [...existing, ...incoming];
          },
        },
      },
    },
    User: {
      keyFields: ['id'],
    },
    Post: {
      keyFields: ['id'],
      fields: {
        comments: {
          merge(existing = [], incoming) {
            return incoming;
          },
        },
      },
    },
  },
});

export const client = new ApolloClient({
  link: from([errorLink, authLink, httpLink]),
  cache,
  defaultOptions: {
    watchQuery: {
      fetchPolicy: 'cache-and-network',
    },
  },
});

Queries#

// hooks/useUser.ts
import { gql, useQuery } from '@apollo/client';

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

interface User {
  id: string;
  name: string;
  email: string;
  avatar: string;
  posts: { id: string; title: string }[];
}

interface GetUserData {
  user: User;
}

interface GetUserVars {
  id: string;
}

export function useUser(id: string) {
  const { data, loading, error, refetch } = useQuery<GetUserData, GetUserVars>(
    GET_USER,
    {
      variables: { id },
      skip: !id,
      notifyOnNetworkStatusChange: true,
    }
  );

  return {
    user: data?.user,
    loading,
    error,
    refetch,
  };
}

// Component usage
function UserProfile({ userId }: { userId: string }) {
  const { user, loading, error } = useUser(userId);

  if (loading) return <Skeleton />;
  if (error) return <Error message={error.message} />;
  if (!user) return <NotFound />;

  return (
    <div>
      <h1>{user.name}</h1>
      <p>{user.email}</p>
    </div>
  );
}

Mutations#

// hooks/useCreatePost.ts
import { gql, useMutation } from '@apollo/client';

const CREATE_POST = gql`
  mutation CreatePost($input: CreatePostInput!) {
    createPost(input: $input) {
      id
      title
      content
      author {
        id
        name
      }
      createdAt
    }
  }
`;

const GET_POSTS = gql`
  query GetPosts {
    posts {
      id
      title
      createdAt
    }
  }
`;

export function useCreatePost() {
  const [createPost, { loading, error }] = useMutation(CREATE_POST, {
    // Update cache after mutation
    update(cache, { data: { createPost } }) {
      const existing = cache.readQuery({ query: GET_POSTS });

      if (existing) {
        cache.writeQuery({
          query: GET_POSTS,
          data: {
            posts: [createPost, ...existing.posts],
          },
        });
      }
    },
    // Or refetch queries
    refetchQueries: [{ query: GET_POSTS }],
  });

  const handleCreate = async (input: CreatePostInput) => {
    try {
      const { data } = await createPost({ variables: { input } });
      return data.createPost;
    } catch (err) {
      throw err;
    }
  };

  return { createPost: handleCreate, loading, error };
}

// Usage
function CreatePostForm() {
  const { createPost, loading } = useCreatePost();

  const handleSubmit = async (values: FormValues) => {
    const post = await createPost(values);
    router.push(`/posts/${post.id}`);
  };

  return (
    <form onSubmit={handleSubmit}>
      {/* form fields */}
      <button type="submit" disabled={loading}>
        {loading ? 'Creating...' : 'Create Post'}
      </button>
    </form>
  );
}

Optimistic Updates#

// Optimistic mutation
const TOGGLE_LIKE = gql`
  mutation ToggleLike($postId: ID!) {
    toggleLike(postId: $postId) {
      id
      isLiked
      likeCount
    }
  }
`;

function useLikePost() {
  const [toggleLike] = useMutation(TOGGLE_LIKE);

  const handleLike = (post: Post) => {
    toggleLike({
      variables: { postId: post.id },
      optimisticResponse: {
        __typename: 'Mutation',
        toggleLike: {
          __typename: 'Post',
          id: post.id,
          isLiked: !post.isLiked,
          likeCount: post.isLiked ? post.likeCount - 1 : post.likeCount + 1,
        },
      },
    });
  };

  return { handleLike };
}

// Optimistic with cache update
const ADD_COMMENT = gql`
  mutation AddComment($postId: ID!, $content: String!) {
    addComment(postId: $postId, content: $content) {
      id
      content
      author {
        id
        name
      }
      createdAt
    }
  }
`;

function useAddComment() {
  const [addComment] = useMutation(ADD_COMMENT, {
    update(cache, { data: { addComment } }, { variables }) {
      cache.modify({
        id: cache.identify({ __typename: 'Post', id: variables.postId }),
        fields: {
          comments(existingComments = []) {
            const newCommentRef = cache.writeFragment({
              data: addComment,
              fragment: gql`
                fragment NewComment on Comment {
                  id
                  content
                  author {
                    id
                    name
                  }
                  createdAt
                }
              `,
            });
            return [...existingComments, newCommentRef];
          },
          commentCount(existing = 0) {
            return existing + 1;
          },
        },
      });
    },
  });

  return { addComment };
}

Pagination#

// Cursor-based pagination
const GET_POSTS = gql`
  query GetPosts($cursor: String, $limit: Int!) {
    posts(cursor: $cursor, limit: $limit) {
      edges {
        node {
          id
          title
          createdAt
        }
        cursor
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
`;

function useInfinitePosts() {
  const { data, loading, fetchMore } = useQuery(GET_POSTS, {
    variables: { limit: 10 },
  });

  const loadMore = () => {
    if (!data?.posts.pageInfo.hasNextPage) return;

    fetchMore({
      variables: {
        cursor: data.posts.pageInfo.endCursor,
        limit: 10,
      },
    });
  };

  return {
    posts: data?.posts.edges.map((e) => e.node) ?? [],
    hasMore: data?.posts.pageInfo.hasNextPage ?? false,
    loading,
    loadMore,
  };
}

// Cache merge policy for pagination
const cache = new InMemoryCache({
  typePolicies: {
    Query: {
      fields: {
        posts: {
          keyArgs: false,
          merge(existing, incoming, { args }) {
            if (!args?.cursor) {
              return incoming;
            }
            return {
              ...incoming,
              edges: [...(existing?.edges || []), ...incoming.edges],
            };
          },
        },
      },
    },
  },
});

Subscriptions#

// Setup WebSocket link
import { split } from '@apollo/client';
import { GraphQLWsLink } from '@apollo/client/link/subscriptions';
import { getMainDefinition } from '@apollo/client/utilities';
import { createClient } from 'graphql-ws';

const wsLink = new GraphQLWsLink(
  createClient({
    url: process.env.NEXT_PUBLIC_WS_URL!,
    connectionParams: {
      authToken: localStorage.getItem('token'),
    },
  })
);

const splitLink = split(
  ({ query }) => {
    const definition = getMainDefinition(query);
    return (
      definition.kind === 'OperationDefinition' &&
      definition.operation === 'subscription'
    );
  },
  wsLink,
  httpLink
);

// Subscription hook
const MESSAGE_SUBSCRIPTION = gql`
  subscription OnMessage($channelId: ID!) {
    messageAdded(channelId: $channelId) {
      id
      content
      author {
        id
        name
      }
      createdAt
    }
  }
`;

function useMessages(channelId: string) {
  const { data, loading } = useQuery(GET_MESSAGES, {
    variables: { channelId },
  });

  useSubscription(MESSAGE_SUBSCRIPTION, {
    variables: { channelId },
    onData: ({ client, data }) => {
      const newMessage = data.data.messageAdded;

      client.cache.modify({
        id: client.cache.identify({ __typename: 'Channel', id: channelId }),
        fields: {
          messages(existing = []) {
            const newMessageRef = client.cache.writeFragment({
              data: newMessage,
              fragment: MESSAGE_FRAGMENT,
            });
            return [...existing, newMessageRef];
          },
        },
      });
    },
  });

  return { messages: data?.messages ?? [], loading };
}

Fragment Colocation#

// Colocate fragments with components
// components/UserAvatar.tsx
export const USER_AVATAR_FRAGMENT = gql`
  fragment UserAvatar on User {
    id
    name
    avatar
  }
`;

export function UserAvatar({ user }: { user: UserAvatarFragment }) {
  return <img src={user.avatar} alt={user.name} />;
}

// Compose fragments in queries
const GET_POST = gql`
  ${USER_AVATAR_FRAGMENT}

  query GetPost($id: ID!) {
    post(id: $id) {
      id
      title
      content
      author {
        ...UserAvatar
      }
    }
  }
`;

Best Practices#

Queries:
✓ Use fragments for reusable fields
✓ Colocate queries with components
✓ Use generated types (codegen)
✓ Handle loading and error states

Mutations:
✓ Use optimistic updates for UX
✓ Update cache properly
✓ Handle errors gracefully
✓ Show loading feedback

Caching:
✓ Configure type policies
✓ Use cache.modify for updates
✓ Normalize data with keyFields
✓ Handle pagination correctly

Apollo Client provides a complete GraphQL solution for React. Master queries and mutations, leverage the cache effectively with type policies, and use optimistic updates for responsive UIs. Colocate fragments with components for maintainability and use subscriptions for real-time features.