●Change8

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

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

Released: 6/13/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:

HttpLinkBatchHttpLinkApolloClientPersistedQueryLinkClientAwarenessLinkBaseHttpLinkBaseBatchHttpLinkHttpOptions

Breaking Changes

●Issue #1

The `includeExtensions` option of `HttpLink` and `BatchHttpLink` now defaults to `true`, which may cause extensions to be sent unintentionally. To retain previous behavior set `includeExtensions: false` in the link options.

●Issue #2

`ApolloClient` constructor options `name` and `version` have been moved under a `clientAwareness` key; update client initialization accordingly.

●Issue #3

Aliasing any field to `__typename` is now forbidden; rename such aliases to a non‑reserved name.

●Issue #4

Aliasing a field to an alias that starts with `__ac_` is now forbidden; avoid using that prefix.

●Issue #5

The default `Accept` header for multipart requests has changed to include `application/graphql-response+json` and a lower‑priority `application/json`; adjust server expectations or override the header if needed.

Migration Steps

  1. 1
    Set `includeExtensions: false` on `HttpLink`/`BatchHttpLink` if you relied on the previous default of false.
  2. 2
    Move `name` and `version` options into a `clientAwareness` object when constructing `ApolloClient`.
  3. 3
    Review GraphQL queries and remove any alias to `__typename` or aliases beginning with `__ac_`.
  4. 4
    If your server expects the old multipart `Accept` header, override it via the new `accept` option or adjust the server to accept the new header format.
  5. 5
    To keep bundle size minimal, replace `HttpLink`/`BatchHttpLink` with `BaseHttpLink`/`BaseBatchHttpLink` if you do not need client awareness features.

Release Summary

This release introduces enhanced client awareness, changes default behaviors for extensions and multipart Accept headers, adds new link utilities, and enforces stricter alias rules, along with a bug fix for persisted queries.

Need More Details?

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

View Full Changelog