●Change8

Migrating to Apollo Client @apollo/client@4.0.0-rc.5

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

Released: 7/18/2025

3
Breaking Changes
4
Migration Steps
10
Affected Symbols

⚠️ Check Your Code

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

client.readQueryclient.readFragmentclient.watchFragmentuseFragmentuseSuspenseFragmentcache.watchFragmentgqlreadFragmentreadQueryInMemoryCache

Breaking Changes

●Issue #1

client.readQuery, client.readFragment, client.watchFragment, useFragment, and useSuspenseFragment now apply document transforms before reading data from the cache, changing previous behavior. To retain the old behavior, use the equivalent cache.readQuery, cache.readFragment, etc.

●Issue #2

cache.watchFragment now returns an Unmasked<TData> result instead of a masked result, which may break TypeScript type expectations.

●Issue #3

The gql export has been removed from the @apollo/client/react entrypoint; import gql from @apollo/client instead.

Migration Steps

  1. 1
    Replace imports of gql from @apollo/client/react with imports from @apollo/client.
  2. 2
    If you need the previous cache‑reading behavior, switch from client.readQuery/client.readFragment/etc. to cache.readQuery, cache.readFragment, etc.
  3. 3
    Update TypeScript code to handle the Unmasked<TData> return type from cache.watchFragment.
  4. 4
    Modify calls to readFragment and readQuery to include the optimistic flag inside the first argument object instead of as a separate second argument.

Release Summary

This release adds improved handling of masked fragments, introduces dataState in watchFragment, normalizes empty argument storage, and updates cache read behavior, while deprecating old readFragment/readQuery signatures and removing gql from the react entrypoint.

Need More Details?

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

View Full Changelog