●Change8

Migrating to Apollo Client @apollo/client@4.0.0

Version @apollo/client@4.0.0 introduces 11 breaking changes. This guide details how to update your code.

Released: 8/21/2025

11
Breaking Changes
13
Migration Steps
22
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

ApolloErrorCombinedGraphQLErrorsServerErrorServerParseErrorUnconventionalErrorLinkErrorLocalStateuseLazyQueryuseMutationuseQueryprerenderStaticHttpLinkSetContextLinkErrorLinkcreateHttpLinksetContext@apollo/client@apollo/client/react@apollo/client/local-state@apollo/client/incremental@apollo/client/react/ssr@apollo/client/react/compiled

Breaking Changes

●Issue #1

React exports moved from `@apollo/client` to `@apollo/client/react`; update import paths.

●Issue #2

`ApolloError` class removed; replace with specific error classes (`CombinedGraphQLErrors`, `ServerError`, etc.).

●Issue #3

`@client` directive functionality is now opt‑in via the `LocalState` class; configure `localState` to use local state.

●Issue #4

Resolver context shape changed: `context` now provides `{ client, requestContext, phase }` instead of `{ cache }`.

●Issue #5

`useLazyQuery` no longer accepts `variables` or `context` options; pass them to the returned `execute` function.

●Issue #6

`useMutation` option `ignoreResults` removed; use `client.mutate` directly for fire‑and‑forget.

●Issue #7

`useQuery` callbacks `onCompleted` and `onError` removed; use effect or error handling via new error classes.

●Issue #8

SSR API `prerenderStatic` replaces previous SSR functions; update imports and usage.

●Issue #9

All link creators (`createHttpLink`, `setContext`, etc.) are now classes (`HttpLink`, `SetContextLink`); instantiate with `new`.

●Issue #10

ErrorLink constructor signature changed to receive `{ error }` and use new error classes.

●Issue #11

Observable implementation switched from `zen-observable` to RxJS; any custom observable code must adapt to RxJS API.

Migration Steps

  1. 1
    Update all React imports to `import { … } from '@apollo/client/react'`.
  2. 2
    Replace `instanceof ApolloError` checks with the new static `.is()` methods (e.g., `CombinedGraphQLErrors.is(error)`).
  3. 3
    If using local state, add `localState: new LocalState({ resolvers: … })` to the client config and remove `@client` directives.
  4. 4
    Adjust resolver functions to use the new context shape (`const { client, requestContext, phase } = context`).
  5. 5
    Refactor `useLazyQuery` calls: remove `variables`/`context` from hook options and pass them to the `execute` function.
  6. 6
    Remove `ignoreResults` from `useMutation` calls; use `client.mutate` directly when you don’t need the result.
  7. 7
    Replace `onCompleted`/`onError` callbacks in `useQuery` with effect hooks or error handling via the new error classes.
  8. 8
    Switch SSR code to import and call `prerenderStatic` from `@apollo/client/react/ssr`.
  9. 9
    Convert link creation from functions to class instances (`new HttpLink(...)`, `new SetContextLink(...)`).
  10. 10
    Update `ErrorLink` usage to accept `{ error }` and use the new error classes for handling.
  11. 11
    If you rely on custom observables, migrate code to RxJS APIs.
  12. 12
    Run the provided codemod: `npx @apollo/client-codemod-migra` to automate many of the above changes.
  13. 13
    Ensure your environment runs on Node >=20 and includes RxJS as a dependency.

Release Summary

Apollo Client 4.0 introduces a framework‑agnostic core, unified error handling, opt‑in local state, a new `dataState` property, and class‑based links, while removing `ApolloError` and several legacy APIs, requiring code migrations.

Need More Details?

View the full release notes and all changes for Apollo Client @apollo/client@4.0.0.

View Full Changelog