●Change8

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

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

Released: 6/6/2025

5
Breaking Changes
5
Migration Steps
8
Affected Symbols

⚠️ Check Your Code

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

ObservableQueryObservableQuery.queryIdApolloClient.getObservableQueriesApolloClient.refetchQueriesApolloClient.stoppreloadQuerypreloadQuery.toPromisequeryRef

Breaking Changes

●Issue #1

ObservableQuery no longer has a `queryId` property; code accessing `queryId` must be removed or replaced.

●Issue #2

`ApolloClient.getObservableQueries` now returns a `Set<ObservableQuery>` instead of a `Map<string, ObservableQuery>`; update code that expects a Map (e.g., iteration over entries) to work with a Set.

●Issue #3

`ObservableQuery`s are only registered with the client while they have subscribers; consequently `ApolloClient.getObservableQueries` and `ApolloClient.refetchQueries` will only return/refetch queries that have at least one subscriber. Adjust logic that relied on previously registered inactive queries.

●Issue #4

`queryRef` objects created by `preloadQuery` no longer have a `.toPromise()` method. Use `preloadQuery.toPromise(queryRef)` instead.

●Issue #5

`ApolloClient.stop()` now unsubscribes all active ObservableQuery instances and rejects in‑flight queries; ensure any custom cleanup logic accounts for the completed events and rejected promises.

Migration Steps

  1. 1
    Remove any usage of `observableQuery.queryId`.
  2. 2
    Replace code that treats the result of `ApolloClient.getObservableQueries` as a Map with code that works with a Set (e.g., use `for (const oq of set)` or convert to an array).
  3. 3
    If you relied on `ApolloClient.getObservableQueries` or `ApolloClient.refetchQueries` returning inactive queries, add explicit subscriptions or adjust logic to handle the new active/inactive definitions.
  4. 4
    Change `await queryRef.toPromise()` to `await preloadQuery.toPromise(queryRef)`.
  5. 5
    If you have custom listeners for the `completed` event from `ApolloClient.stop()`, verify they still behave as expected after the aggressive cleanup.

Release Summary

Apollo Client 8 introduces breaking API changes: ObservableQuery loses its queryId, getObservableQueries now returns a Set, and preloadQuery’s toPromise API changes, while adding a new ObservableQuery.stop method and more aggressive client cleanup.

Need More Details?

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

View Full Changelog