●Change8

Migrating to Apollo Client @apollo/client@4.0.0-alpha.23

Version @apollo/client@4.0.0-alpha.23 introduces 5 breaking changes. This guide details how to update your code.

Released: 6/18/2025

5
Breaking Changes
5
Migration Steps
14
Affected Symbols

⚠️ Check Your Code

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

fetchMoreclient.reFetchObservableQueriesclient.refetchQueriesuseQueryObservableQuery.getCurrentResultcreatePersistedQueryLinkonErrorNetworkStatussetContextSetContextLinkcreateHttpLinkHttpLinkcreatePersistedQueryLinkPersistedQueryLink

Breaking Changes

●Issue #1

The `ErrorResponse` object passed to the `disable` and `retry` callback options provided to `createPersistedQueryLink` no longer provides separate `graphQLErrors` and `networkError` properties; they are combined into a single `error` property of type `ErrorLike`. You must update checks from checking `graphQLErrors` or `networkError` to checking the unified `error` property and using type guards like `CombinedGraphQLErrors.is(error)` or `ServerError.is(error)`.

●Issue #2

The `response` property in `onError` link callback and in `createPersistedQueryLink` callbacks has been renamed to `result`. This affects how you access the response data in these handlers.

●Issue #3

When specifying the `query` option in `fetchMore`, options are now inherited from the underlying `ObservableQuery` for all unspecified options except `variables`. Previously, if `query` was specified, no options were inherited.

●Issue #4

The `errorPolicy` of `fetchMore` now defaults to `"none"` instead of inheriting from the `ObservableQuery` options. This prevents accidental cache writes of partial data for paginated queries.

●Issue #5

Calling `fetchMore` on a `cache-only` query now throws an error.

Migration Steps

  1. 1
    Migrate link creation from functions to classes: replace `setContext(...)` with `new SetContextLink(...)`, `createHttpLink(...)` with `new HttpLink(...)`, and `createPersistedQueryLink(...)` with `new PersistedQueryLink(...)`.
  2. 2
    Update code using `createPersistedQueryLink` callbacks to use the unified `error` property instead of separate `graphQLErrors` and `networkError`.
  3. 3
    Update code accessing response data in `onError` link callbacks and `createPersistedQueryLink` callbacks to use `result` instead of `response`.
  4. 4
    If you relied on `fetchMore` inheriting `errorPolicy` from the underlying query, explicitly pass the desired `errorPolicy` to `fetchMore` as it now defaults to `"none"`.
  5. 5
    Avoid calling `fetchMore` on queries with `fetchPolicy: 'cache-only'`.

Release Summary

This release introduces significant improvements to `cache-only` query behavior, making them more predictable by preventing unnecessary fetches and initial loading states. It also modernizes link creation by favoring classes over creator functions and refines option inheritance in `fetchMore`.

Need More Details?

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

View Full Changelog