●Change8

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

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

Released: 8/1/2025

12
Breaking Changes
12
Migration Steps
18
Affected Symbols

⚠️ Check Your Code

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

operation.getContextApolloLink.RequestApolloLink.executeoperation.operationTypeoperation.operationNameApolloLink.concatApolloLink.fromApolloLink.splittransformOperationvalidateOperationcreateOperationGraphQLRequestApolloLink.OperationObservableEMPTYApolloLink.ForwardFunctionApolloLink.ResultApolloLink namespace types (FetchResult, GraphQLRequest, NextLink)

Breaking Changes

●Issue #1

operation.getContext now returns a Readonly<OperationContext>, breaking code that mutates the context object.

●Issue #2

ApolloLink.Request passed to ApolloLink.execute no longer accepts operationName and operationType options; these must be removed from request objects.

●Issue #3

operation.operationType is now a non-null OperationTypeNode, so code that checks for undefined must be updated.

●Issue #4

operation.operationName is now string | undefined (undefined for anonymous queries) instead of empty string.

●Issue #5

ApolloLink.concat, ApolloLink.from and ApolloLink.split no longer accept a plain request handler function; handlers must be wrapped in new ApolloLink.

●Issue #6

transformOperation and validateOperation have been removed from @apollo/client/link/utils; callers must stop importing them and rely on createOperation.

●Issue #7

Request handlers must now return an Observable; returning null is no longer allowed. Use RxJS EMPTY observable instead.

●Issue #8

createOperation no longer accepts a context argument as the first parameter; context must be provided in the request object.

●Issue #9

The TVariables generic argument has been removed from the GraphQLRequest type.

●Issue #10

The context object returned from operation.getContext() is now frozen, breaking code that mutates it.

●Issue #11

The forward function is now always provided to request handlers and is no longer optional; custom link signatures must be updated.

●Issue #12

ApolloLink no longer detects terminating links by function arity, changing warning behavior when forward is called on a terminating link.

Migration Steps

  1. 1
    Update code that mutates the object returned by operation.getContext(); treat it as read-only.
  2. 2
    Remove operationName and operationType from GraphQLRequest objects passed to ApolloLink.execute.
  3. 3
    Adjust checks for operation.operationType to remove undefined handling.
  4. 4
    Handle operation.operationName possibly being undefined instead of empty string.
  5. 5
    Wrap plain request handler functions with new ApolloLink when using concat, from, or split.
  6. 6
    Stop importing transformOperation and validateOperation; rely on createOperation to produce a well-formed Operation.
  7. 7
    Change request handlers to return an Observable; replace null returns with RxJS EMPTY.
  8. 8
    Pass context inside the request object to createOperation instead of as a separate argument.
  9. 9
    Remove the TVariables generic from GraphQLRequest type usages.
  10. 10
    Do not attempt to mutate the context object returned from operation.getContext(); it is now frozen.
  11. 11
    Update custom link request method signatures to make forward a required parameter.
  12. 12
    Be aware that ApolloLink no longer warns about using concat on terminating links; ensure forward is not called on terminating links.

Release Summary

This release introduces several breaking TypeScript API changes—including read-only operation contexts, removal of certain request fields, and stricter link handler requirements—while adding features like multi-link concatenation and improved type safety.

Need More Details?

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

View Full Changelog