@apollo/client

Minor Changes

Fetching with Suspense

• Add support for React suspense with a new useSuspenseQuery hook.

  useSuspenseQuery initiates a network request and causes the component calling it to suspend while the request is in flight. It can be thought of as a drop-in replacement for useQuery that allows you to take advantage of React's concurrent features while fetching during render.

  Consider a Dog component that fetches and renders some information about a dog named Mozzarella:

  View code 🐶

  import { Suspense } from "react";
  import { gql, TypedDocumentNode, useSuspenseQuery } from "@apollo/client";
  
  interface Data {
    dog: {
      id: string;
      name: string;
    };
  }
  
  interface Variables {
    name: string;
  }
  
  const GET_DOG_QUERY: TypedDocumentNode<Data, Variables> = gql`
    query GetDog($name: String) {
      dog(name: $name) {
        id
        name
      }
    }
  `;
  
  function App() {
    return (
      <Suspense fallback={<div>Loading...</div>}>
        <Dog name="Mozzarella" />
      </Suspense>
    );
  }
  
  function Dog({ name }: { name: string }) {
    const { data } = useSuspenseQuery(GET_DOG_QUERY, {
      variables: { name },
    });
  
    return <>Name: {data.dog.name}</>;
  }

  For a detailed explanation of useSuspenseQuery, see our fetching with Suspense reference.

• Adds useBackgroundQuery and useReadQuery hooks

  useBackgroundQuery initiates a request for data in a parent component and returns a QueryReference which is used to read the data in a child component via useReadQuery. If the child component attempts to render before the data can be found in the cache, the child component will suspend until the data is available. On cache updates to watched data, the child component calling useReadQuery will re-render with new data but the parent component will not re-render (as it would, for example, if it were using useQuery to issue the request).

  Consider an App component that fetches a list of breeds in the background while also fetching and rendering some information about an individual dog, Mozzarella:

  View code 🐶

  function App() {
    const [queryRef] = useBackgroundQuery(GET_BREEDS_QUERY);
    return (
      <Suspense fallback={<div>Loading...</div>}>
        <Dog name="Mozzarella" queryRef={queryRef} />
      </Suspense>
    );
  }
  
  function Dog({
    name,
    queryRef,
  }: {
    name: string;
    queryRef: QueryReference<BreedData>;
  }) {
    const { data } = useSuspenseQuery(GET_DOG_QUERY, {
      variables: { name },
    });
    return (
      <>
        Name: {data.dog.name}
        <Suspense fallback={<div>Loading breeds...</div>}>
          <Breeds queryRef={queryRef} />
        </Suspense>
      </>
    );
  }
  
  function Breeds({ queryRef }: { queryRef: QueryReference<BreedData> }) {
    const { data } = useReadQuery(queryRef);
    return data.breeds.map(({ characteristics }) =>
      characteristics.map((characteristic) => (
        <div key={characteristic}>{characteristic}</div>
      ))
    );
  }

  For a detailed explanation of useBackgroundQuery and useReadQuery, see our fetching with Suspense reference.

Document transforms

• Add the ability to specify custom GraphQL document transforms. These transforms are run before reading data from the cache, before local state is resolved, and before the query document is sent through the link chain.

  To register a custom document transform, create a transform using the DocumentTransform class and pass it to the documentTransform option on ApolloClient.

  import { DocumentTransform } from "@apollo/client";
  
  const documentTransform = new DocumentTransform((document) => {
    // do something with `document`
    return transformedDocument;
  });
  
  const client = new ApolloClient({ documentTransform: documentTransform });

  For more information on the behavior and API of DocumentTransform, see its reference page in our documentation.

New removeTypenameFromVariables link

• Introduce the new removeTypenameFromVariables link. This link will automatically remove __typename fields from variables for all operations. This link can be configured to exclude JSON-scalars for scalars that utilize __typename.

  This change undoes some work from #10724 where __typename was automatically stripped for all operations with no configuration. This was determined to be a breaking change and therefore moved into this link.

  For a detailed explanation of removeTypenameFromVariables, see its API reference.

New skipToken sentinel

• deprecated

  Adds support for a skipToken sentinel that can be used as options in useSuspenseQuery and useBackgroundQuery to skip execution of a query. This works identically to the skip option but is more type-safe and as such, becomes the recommended way to skip query execution. As such, the skip option has been deprecated in favor of skipToken.

  We are considering the removal of the skip option from useSuspenseQuery and useBackgroundQuery in the next major. We are releasing with it now to make migration from useQuery easier and make skipToken more discoverable.

  useSuspenseQuery

  import { skipToken, useSuspenseQuery } from "@apollo/client";
  
  const id: number | undefined;
  
  const { data } = useSuspenseQuery(
    query,
    id ? { variables: { id } } : skipToken
  );

  useBackgroundQuery

  import { skipToken, useBackgroundQuery } from "@apollo/client";
  
  function Parent() {
    const [queryRef] = useBackgroundQuery(
      query,
      id ? { variables: { id } } : skipToken
    );
  
    return queryRef ? <Child queryRef={queryRef} /> : null;
  }
  
  function Child({ queryRef }: { queryRef: QueryReference<TData> }) {
    const { data } = useReadQuery(queryRef);
  }

  For a detailed explanation of skipToken, see its API reference.

New error extraction mechanism, smaller bundles

• Add a new mechanism for Error Extraction to reduce bundle size by including error message texts on an opt-in basis.

  By default, errors will link to an error page with the entire error message.
  This replaces "development" and "production" errors and works without
  additional bundler configuration.

  Bundling the text of error messages and development warnings can be enabled as follows:

  import { loadErrorMessages, loadDevMessages } from "@apollo/client/dev";
  if (process.env.NODE_ENV !== "production") {
    loadErrorMessages();
    loadDevMessages();
  }

  For a detailed explanation, see our reference on reducing bundle size.

New @nonreactive directive

• Implement a @nonreactive directive for selectively skipping reactive comparisons of query result subtrees.

  The @nonreactive directive can be used to mark query fields or fragment spreads and is used to indicate that changes to the data contained within the subtrees marked @nonreactive should not trigger re-rendering. This allows parent components to fetch data to be rendered by their children without re-rendering themselves when the data corresponding with fields marked as @nonreactive change.

  Consider an App component that fetches and renders a list of ski trails:

  View code 🎿

  const TrailFragment = gql`
    fragment TrailFragment on Trail {
      name
      status
    }
  `;
  
  const ALL_TRAILS = gql`
    query allTrails {
      allTrails {
        id
        ...TrailFragment @nonreactive
      }
    }
    ${TrailFragment}
  `;
  
  function App() {
    const { data, loading } = useQuery(ALL_TRAILS);
    return (
      <main>
        <h2>Ski Trails</h2>
        <ul>
          {data?.trails.map((trail) => (
            <Trail key={trail.id} id={trail.id} />
          ))}
        </ul>
      </main>
    );
  }

  The Trail component renders a trail's name and status and allows the user to execute a mutation to toggle the status of the trail between "OPEN" and "CLOSED":

  View code 🎿

  const Trail = ({ id }) => {
    const [updateTrail] = useMutation(UPDATE_TRAIL);
    const { data } = useFragment({
      fragment: TrailFragment,
      from: {
        __typename: "Trail",
        id,
      },
    });
    return (
      <li key={id}>
        {data.name} - {data.status}
        <input
          checked={data.status === "OPEN" ? true : false}
          type="checkbox"
          onChange={(e) => {
            updateTrail({
              variables: {
                trailId: id,
                status: e.target.checked ? "OPEN" : "CLOSED",
              },
            });
          }}
        />
      </li>
    );
  };

  Notice that the Trail component isn't receiving the entire trail object via props, only the id which is used along with the fragment document to create a live binding for each trail item in the cache. This allows each Trail component to react to the cache updates for a single trail independently. Updates to a trail's status will not cause the parent App component to rerender since the @nonreactive directive is applied to the TrailFragment spread, a fragment that includes the status field.

  For a detailed explanation, see our @nonreactive reference and @alessbell's post on the Apollo blog about using @nonreactive with useFragment.

Abort the AbortController signal more granularly

• HttpLink/BatchHttpLink: Abort the AbortController signal more granularly.

  Before this change, when HttpLink/BatchHttpLink created an AbortController internally, the signal would always be .aborted after the request was completed. This could cause issues with Sentry Session Replay and Next.js App Router Cache invalidations, which just replayed the fetch with the same options - including the cancelled AbortSignal.

  With this change, the AbortController will only be .abort()ed by outside events, not as a consequence of the request completing.

useFragment drops its experimental label

• Remove experimental labels.

  useFragment, introduced in 3.7.0 as useFragment_experimental, is no longer an experimental API 🎉 We've removed the _experimental suffix from its named export and have made a number of improvements.

  For a detailed explanation, see our useFragment reference and @alessbell's post on the Apollo blog about using useFragment with @nonreactive for improved performance when rendering lists.

  useFragment improvements

  • More robust types for the data property on UseFragmentResult. When a partial result is given, the type is now correctly set to Partial<TData>.

  • Adjust the rerender timing of useQuery to more closely align with useFragment. This means that cache updates delivered to both hooks should trigger renders at relatively the same time. Previously, the useFragment might rerender much faster leading to some confusion.

  • Remove the deprecated returnPartialData option from useFragment hook.

More Minor Changes

• Add generic type parameter for the entity modified in cache.modify. Improves TypeScript type inference for that type's fields and values of those fields.

  Example:

  cache.modify<Book>({
    id: cache.identify(someBook),
    fields: {
      title: (title) => {
        // title has type `string`.
        // It used to be `any`.
      },
   => {
        // author has type `Reference | Book["author"]`.
        // It used to be `any`.
      },
    },
  });

• Use unique opaque types for the DELETE and INVALIDATE Apollo cache modifiers.

  This increases type safety, since these 2 modifiers no longer have the any type. Moreover, it no longer triggers the @typescript-eslint/no-unsafe-return
  rule.

• Avoid calling useQuery onCompleted for cache writes

• removed

  Remove the query/mutation/subscription option from hooks that already take that value as their first argument.

• Prevent accidental widening of inferred TData and TVariables generics for query hook option arguments

• Simplify __DEV__ polyfill to use imports instead of global scope

• Add .js file extensions to imports in src and dist/*/.d.ts

• When changing variables back to a previously used set of variables, do not automatically cache the result as part of the query reference. Instead, dispose of the query reference so that the InMemoryCache can determine the cached behavior. This means that fetch policies that would guarantee a network request are now honored when switching back to previously used variables.

• (Batch)HttpLink: Propagate AbortErrors to the user when a user-provided signal is passed to the link. Previously, these links would swallow all AbortErrors, potentially causing queries and mutations to never resolve. As a result of this change, users are now expected to handle AbortErrors when passing in a user-provided signal.

• Add the ability to allow @client fields to be sent to the link chain.

• Allow ApolloCache implementations to specify default value for assumeImmutableResults client option, improving performance for applications currently using InMemoryCache without configuring new ApolloClient({ assumeImmutableResults: true })

• Changes how development-only code is bundled in the library to more reliably enable consuming bundlers to reduce production bundle sizes while keeping compatibility with non-node environments.

Patch Changes

• Fix an issue where a call to refetch, fetchMore, or changing skip to false that returned a result deeply equal to data in the cache would get stuck in a pending state and never resolve.

• Add SuspenseCache as a lazy hidden property on ApolloClient.
  This means that SuspenseCache is now an implementation details of Apollo Client and you no longer need to manually instantiate it and no longer need to pass it into ApolloProvider. Trying to instantiate a SuspenseCache instance in your code will now throw an error.

• Enforce export type for all type-level exports.

• Prevents the DevTool installation warning to be turned into a documentation link.

• Add a suspenseCache option to useSuspenseQuery

• Add a queryKey option to useSuspenseQuery that allows the hook to create a unique subscription instance.

• Automatically strips __typename fields from variables sent to the server when using HttpLink, BatchHttpLink, or GraphQLWsLink. This allows GraphQL data returned from a query to be used as an argument to a subsequent GraphQL operation without the need to strip the __typename in user-space.

• Use React.version as key for shared Contexts.

• Fix an issue where cache updates would not propagate to useSuspenseQuery while in strict mode.

• Make private fields inFlightLinkObservables and fetchCancelFns protected in QueryManager in order to make types available in @apollo/experimental-nextjs-app-support package when extending the ApolloClient class.

• Ensure Context value stability when rerendering ApolloProvider with the same client and/or suspenseCache prop

• Fixes a bug in useMutation so that onError is called when an error is returned from the request with errorPolicy set to 'all' .

• Return networkStatus in the useSuspenseQuery result.

• Moves DocumentTransform to the utilities sub-package to avoid a circular dependency between the core and cache sub-packages.

• Improve useBackgroundQuery type interface

• Fixes an issue where useSuspenseQuery would not respond to cache updates when using a cache-first fetchPolicy after the hook was mounted with data already in the cache.

• Store React.Context instance mapped by React.createContext instance, not React.version.
  Using React.version can cause problems with preact, as multiple versions of preact will all identify themselves as React 17.0.2.

• Use import * as React everywhere. This prevents an error when importing @apollo/client in a React Server component. (see #10974)

• Fix a bug in QueryReference where this.resolve or this.reject might be executed even if undefined.

• Add support for the skip option in useBackgroundQuery and useSuspenseQuery. Setting this option to true will avoid a network request.

• Fix the compatibility between useSuspenseQuery and React's useDeferredValue and startTransition APIs to allow React to show stale UI while the changes to the variable cause the component to suspend.

Breaking change

nextFetchPolicy support has been removed from useSuspenseQuery. If you are using this option, remove it, otherwise it will be ignored.

• breaking

  Fixes a bug in BatchHttpLink that removed variables from all requests by default.

• breaking

  Fix type policy inheritance involving fuzzy possibleTypes

• breaking

  Fix includeUnusedVariables option not working with BatchHttpLink

• breaking

  useBackgroundQuery now uses its own options type called BackgroundQueryHookOptions rather than reusing SuspenseQueryHookOptions.

• breaking

  Incrementally re-render deferred queries after calling refetch or setting skip to false to match the behavior of the initial fetch. Previously, the hook would not re-render until the entire result had finished loading in these cases.

• breaking

  Silence useLayoutEffect warning when useSuspenseQuery runs on server

• breaking

  Fix an issue when using a link that relied on operation.getContext and operation.setContext would error out when it was declared after the removeTypenameFromVariables link.

• breaking

  Use printed query for query deduplication. Cache print calls for GraphQL documents to speed up repeated operations.

• breaking

  Introduced some helpers for determining the type of operation for a GraphQL query. This imported the OperationTypeNode from graphql-js which is not available in GraphQL 14. To maintain compatibility with graphql-js v14, this has been reverted to use plain strings.

• breaking

  More robust typings for the data property returned from useSuspenseQuery when using returnPartialData: true or an errorPolicy of all or ignore. TData now defaults to unknown instead of any.

• breaking

  Always throw network errors in useSuspenseQuery regardless of the set errorPolicy.

• breaking

  Change an import in useQuery and useMutation that added an unnecessary runtime dependency on @apollo/client/core. This drastically reduces the bundle size of each the hooks.

• breaking

  Ensure refetch, fetchMore, and subscribeToMore functions returned by useSuspenseQuery are referentially stable between renders, even as data is updated.

• breaking

  Add @defer support to useSuspenseQuery.

• breaking

  Updates dependency versions in package.json by bumping:

  • @wry/context to ^0.7.3

  • @wry/equality to ^0.5.6

  • @wry/trie to ^0.4.3

  • optimism to ^0.17.4

  to 1. fix sourcemap warnings and 2. a Codesandbox sandpack (in-browser) bundler transpilation bug with an upstream optimism workaround.

• breaking

  Hide queryRef in a Symbol in useBackgroundQuerys return value.

• breaking

  Use React.use where available

• breaking

  Throw errors in useSuspenseQuery for errors returned in incremental chunks when errorPolicy is none. This provides a more consistent behavior of the errorPolicy in the hook.

Potentially breaking change

Previously, if you issued a query with @defer and relied on errorPolicy: 'none' to set the error property returned from useSuspenseQuery when the error was returned in an incremental chunk, this error is now thrown. Switch the errorPolicy to all to avoid throwing the error and instead return it in the error property.

• breaking

  Adds support for returnPartialData and refetchWritePolicy options in useBackgroundQuery hook.

• breaking

  Fixed the ability to use refetch and fetchMore with React's startTransition. The hook will now behave correctly by allowing React to avoid showing the Suspense fallback when these functions are wrapped by startTransition. This change deprecates the suspensePolicy option in favor of startTransition.

• breaking

  Restore Apollo Client 3.7 getApolloContext behaviour

• breaking

  Slightly decrease bundle size and memory footprint of SuspenseCache by changing how cache entries are stored internally.

• breaking

  useSuspenseQuery and useBackgroundQuery will now properly apply changes to its options between renders.

• breaking

  The "per-React-Version-Singleton" ApolloContext is now stored on globalThis, not React.createContext, and throws an error message when accessed from React Server Components.

• breaking

  Add support for the subscribeToMore and client fields returned in the useSuspenseQuery result.