â—ŹChange8

@apollo/client@4.0.0

Breaking Changes
📦 apollo-client
⚠ 11 breaking✨ 9 features⚡ 3 deprecations🔧 22 symbols

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.

⚠️ Breaking Changes

  • React exports moved from `@apollo/client` to `@apollo/client/react`; update import paths.
  • `ApolloError` class removed; replace with specific error classes (`CombinedGraphQLErrors`, `ServerError`, etc.).
  • `@client` directive functionality is now opt‑in via the `LocalState` class; configure `localState` to use local state.
  • Resolver context shape changed: `context` now provides `{ client, requestContext, phase }` instead of `{ cache }`.
  • `useLazyQuery` no longer accepts `variables` or `context` options; pass them to the returned `execute` function.
  • `useMutation` option `ignoreResults` removed; use `client.mutate` directly for fire‑and‑forget.
  • `useQuery` callbacks `onCompleted` and `onError` removed; use effect or error handling via new error classes.
  • SSR API `prerenderStatic` replaces previous SSR functions; update imports and usage.
  • All link creators (`createHttpLink`, `setContext`, etc.) are now classes (`HttpLink`, `SetContextLink`); instantiate with `new`.
  • ErrorLink constructor signature changed to receive `{ error }` and use new error classes.
  • Observable implementation switched from `zen-observable` to RxJS; any custom observable code must adapt to RxJS API.

Migration Steps

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

✨ New Features

  • Framework‑agnostic core with React exports in `@apollo/client/react`.
  • Opt‑in local state management via `LocalState` class.
  • Unified error handling with specific error classes and static `.is()` type guards.
  • `dataState` property on query results for precise completeness tracking.
  • Pluggable incremental delivery support with `Defer20220824Handler`.
  • React Compiler‑optimized compiled hooks (`@apollo/client/react/compiled`).
  • New SSR API `prerenderStatic` for React 19 prerendering.
  • Link system now uses class‑based links (`HttpLink`, `SetContextLink`).
  • Migration codemod (`@apollo/client-codemod-migra`).

🔧 Affected Symbols

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

⚡ Deprecations

  • `onCompleted` and `onError` callbacks in `useQuery` are deprecated and removed.
  • Old link creator functions (`createHttpLink`, `setContext`) are deprecated in favor of class‑based links.
  • Legacy SSR functions are deprecated; use `prerenderStatic`.