●Change8

@apollo/client-codemod-migrate-3-to-4@1.0.0

Breaking Changes
📦 apollo-client
⚠ 2 breaking✨ 5 features⚡ 4 deprecations🔧 14 symbols

Summary

Apollo Client 4.x introduces extensive migration tooling, renames import entry points, and overhauls client setup options, requiring developers to run codemods and adjust configuration.

⚠️ Breaking Changes

  • Import paths have moved from the 3.x entrypoint to the new 4.x entrypoint; existing imports will break unless updated.
  • Client setup options have been renamed or relocated (e.g., `uri`, `headers`, `credentials` moved to `link` with a new `HttpLink`; `name`/`version` moved to `clientAwareness`; `connectToDevTools` renamed to `devtools.enabled`; `disableNetworkFetches` renamed to `prioritizeCacheValues`). Code using the old options will break.

Migration Steps

  1. Run `npx @apollo/client-codemod-migrate-3-to-4 --parser tsx ./src/**/*.{ts,tsx}` (supports .js, .jsx, .ts, .tsx) to update import paths.
  2. Apply the `clientSetup` codemod to adjust client configuration: move `uri`, `headers`, `credentials` into a new `HttpLink` under `link`; move `name`/`version` into `clientAwareness`; replace `connectToDevTools` with `devtools.enabled`; rename `disableNetworkFetches` to `prioritizeCacheValues`; add `localState` with `LocalState` and move `resolvers`; remove `typeDefs` and `fragmentMatcher`; add `incrementalHandler` and related type augmentation templates.
  3. If `dataMasking` is enabled, add the provided global type augmentation template.
  4. If using custom links, add the `incrementalHandler` option and the corresponding type augmentation.
  5. Run the updated codemod to remove `TCacheShape` type arguments from all `ApolloClient` usages.
  6. Update any imports of `gql` from `@apollo/client/react` to import from `@apollo/client`.
  7. Replace legacy entry point imports (e.g., `@apollo/client/main.cjs`, `@apollo/client/react/react.cjs`) with the new entry points (`@apollo/client`, `@apollo/client/react`).

✨ New Features

  • Added codemod `@apollo/client-codemod-migrate-3-to-4` to automatically rename old 3.x import locations to 4.x.
  • Introduced `clientSetup` codemod step that migrates Apollo Client setup code to the new configuration schema.
  • Extended `imports` codemod with new `links` and `removals` transformations.
  • Added `legacyEntryPoints` transformation step that updates imports from legacy entry points (e.g., `@apollo/client/main.cjs`) to modern entry points.
  • Codemod now removes the `TCacheShape` type argument from all `ApolloClient` usages.

🔧 Affected Symbols

ApolloClientHttpLinkLocalStateclientAwarenessdevtools.enabledprioritizeCacheValuesincrementalHandlergql@apollo/client/main.cjs@apollo/client/react/react.cjs@apollo/client@apollo/client/reactTCacheShape@apollo/client-codemod-migrate-3-to-4

⚡ Deprecations

  • `disableNetworkFetches` option is deprecated and replaced by `prioritizeCacheValues`.
  • `connectToDevTools` option is deprecated and replaced by `devtools.enabled`.
  • `typeDefs` and `fragmentMatcher` options are removed from client configuration.
  • `gql` is no longer exported from `@apollo/client/react`; import it from `@apollo/client` instead.