@apollo/client

What is @apollo/client?

The @apollo/client npm package is a comprehensive state management library for JavaScript that enables you to manage both local and remote data with GraphQL. It is designed to help you develop faster and more secure apps with less boilerplate. It integrates seamlessly with any JavaScript front-end, allowing for reactive data fetching, caching, and data management.

What are @apollo/client's main functionalities?

Fetching data with useQuery

This feature allows you to fetch data from a GraphQL server. The useQuery hook is used to execute a GraphQL query and handle loading, error, and result states.

import { useQuery, gql } from '@apollo/client';

const GET_LAUNCHES = gql`
  query GetLaunches {
    launches {
      id
      mission_name
    }
  }
`;

function Launches() {
  const { loading, error, data } = useQuery(GET_LAUNCHES);

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

  return data.launches.map(({ id, mission_name }) => (
    <div key={id}>
      <p>{mission_name}</p>
    </div>
  ));
}

Updating data with useMutation

This feature enables you to update data on a GraphQL server. The useMutation hook is used to execute a mutation, allowing you to create, update, or delete data.

import { useMutation, gql } from '@apollo/client';

const ADD_TODO = gql`
  mutation AddTodo($type: String!) {
    addTodo(type: $type) {
      id
      type
    }
  }
`;

function AddTodo() {
  let input;
  const [addTodo, { data }] = useMutation(ADD_TODO);

  return (
    <div>
      <form
        onSubmit={e => {
          e.preventDefault();
          addTodo({ variables: { type: input.value } });
          input.value = '';
        }}
      >
        <input
          ref={node => {
            input = node;
          }}
        />
        <button type="submit">Add Todo</button>
      </form>
    </div>
  );
}

Managing local state

This feature allows you to manage local state using Apollo Client. You can read and write to the cache as if it were a local database, enabling you to manage client-side state alongside remote data.

import { gql, useApolloClient } from '@apollo/client';

const GET_LOCAL_STATE = gql`
  query GetLocalState {
    isLoggedIn @client
  }
`;

function LoginButton() {
  const client = useApolloClient();
  const data = client.readQuery({ query: GET_LOCAL_STATE });
  const isLoggedIn = data.isLoggedIn;

  return (
    <button onClick={() => {
      client.writeQuery({
        query: GET_LOCAL_STATE,
        data: { isLoggedIn: !isLoggedIn }
      });
    }}>
      {isLoggedIn ? 'Log out' : 'Log in'}
    </button>
  );
}

Other packages similar to @apollo/client

relay

Relay is a JavaScript framework for building data-driven React applications with GraphQL. It is similar to @apollo/client in that it provides a powerful and efficient way to fetch and manage GraphQL data. Relay focuses on performance optimizations and static query generation, which can make it more suitable for complex, large-scale applications with high performance requirements.

urql

urql is a highly customizable and versatile GraphQL client for React, Vue, Svelte, and other JavaScript frameworks. It offers a simpler and more flexible approach compared to @apollo/client, with features like document caching and subscriptions. urql's extensibility and plugin system make it a good choice for developers looking for a lightweight and adaptable GraphQL client.

README

Apollo Client

Apollo Client is a fully-featured caching GraphQL client with integrations for React, Angular, and more. It allows you to easily build UI components that fetch data via GraphQL.

☑️ Apollo Client User Survey
What do you like best about Apollo Client? What needs to be improved? Please tell us by taking a one-minute survey. Your responses will help us understand Apollo Client usage and allow us to serve you better.

Documentation

All Apollo Client documentation, including React integration articles and helpful recipes, can be found at:
https://www.apollographql.com/docs/react/

The Apollo Client API reference can be found at:
https://www.apollographql.com/docs/react/api/apollo-client/

Learn how to use Apollo Client with self-paced hands-on training on Odyssey, Apollo's official learning platform:
https://odyssey.apollographql.com/

Maintainers

Name	Username
Ben Newman	@benjamn
Alessia Bellisario	@alessbell
Jeff Auriemma	@bignimbus
Hugh Willson	@hwillson
Jerel Miller	@jerelmiller
Lenz Weber-Tronic	@phryneas

Who is Apollo?

Apollo builds open-source software and a graph platform to unify GraphQL across your apps and services. We help you ship faster with:

• Apollo Studio – A free, end-to-end platform for managing your GraphQL lifecycle. Track your GraphQL schemas in a hosted registry to create a source of truth for everything in your graph. Studio provides an IDE (Apollo Explorer) so you can explore data, collaborate on queries, observe usage, and safely make schema changes.
• Apollo Federation – The industry-standard open architecture for building a distributed graph. Use Apollo’s gateway to compose a unified graph from multiple subgraphs, determine a query plan, and route requests across your services.
• Apollo Client – The most popular GraphQL client for the web. Apollo also builds and maintains Apollo iOS and Apollo Kotlin.
• Apollo Server – A production-ready JavaScript GraphQL server that connects to any microservice, API, or database. Compatible with all popular JavaScript frameworks and deployable in serverless environments.

Learn how to build with Apollo

Check out the Odyssey learning platform, the perfect place to start your GraphQL journey with videos and interactive code challenges. Join the Apollo Community to interact with and get technical help from the GraphQL community.

Changelog

3.10.4

Patch Changes

• #11838 8475346 Thanks @alex-kinokon! - Don’t prompt for DevTools installation for browser extension page

• #11839 6481fe1 Thanks @jerelmiller! - Fix a regression in 3.9.5 where a merge function that returned an incomplete result would not allow the client to refetch in order to fulfill the query.

• #11844 86984f2 Thanks @jerelmiller! - Honor the @nonreactive directive when using cache.watchFragment or the useFragment hook to avoid rerendering when using these directives.

• #11824 47ad806 Thanks @phryneas! - Create branded QueryRef type without exposed properties.

  This change deprecates QueryReference in favor of a QueryRef type that doesn't expose any properties. This change also updates preloadQuery to return a new PreloadedQueryRef type, which exposes the toPromise function as it does today. This means that query refs produced by useBackgroundQuery and useLoadableQuery now return QueryRef types that do not have access to a toPromise function, which was never meant to be used in combination with these hooks.

  While we tend to avoid any types of breaking changes in patch releases as this, this change was necessary to support an upcoming version of the React Server Component integration, which needed to omit the toPromise function that would otherwise have broken at runtime. Note that this is a TypeScript-only change. At runtime, toPromise is still present on all queryRefs currently created by this package - but we strongly want to discourage you from accessing it in all cases except for the PreloadedQueryRef use case.

  Migration is as simple as replacing all references to QueryReference with QueryRef, so it should be possible to do this with a search & replace in most code bases:

  -import { QueryReference } from '@apollo/client'
  +import { QueryRef } from '@apollo/client'
  
  - function Component({ queryRef }: { queryRef: QueryReference<TData> }) {
  + function Component({ queryRef }: { queryRef: QueryRef<TData> }) {
    // ...
  }
  

• #11845 4c5c820 Thanks @jerelmiller! - Remove @nonreactive directives from queries passed to MockLink to ensure they are properly matched.

• #11837 dff15b1 Thanks @jerelmiller! - Fix an issue where a polled query created in React strict mode may not stop polling after the component unmounts while using the cache-and-network fetch policy.