GraphQL Client Integration Knowledge Modules

The seam between a GraphQL server and a typed frontend is where schema drift lands: the server loosens a nullability or removes a field, every committed document stays "valid", and the frontend's generated types quietly stop describing reality. This module covers the client half of that seam — Apollo Client 4 and the v3 muscle memory it invalidates, mutations and cache normalization, typed codegen and the two vendors' opposing guidance, and the three-check drift pipeline in which the obvious check is the weakest. The server-side counterpart for Phoenix backends — schema anatomy, error patterns, dataloader, SDL export — is the elixir domain's absinthe module. The drift pipeline itself is server-agnostic: it works against any exported SDL. This module documents Apollo Client — the most common client and the one with the most version-specific traps. If the repo uses urql, graphql-request, TanStack Query or bare fetch, the cache and hook material below does not apply — only the codegen and Schema Drift sections carry over. Check package.json before relying on any of it. Current versions on npm, 2026-08-08: @apollo/client 4.2.10, urql 5.0.3, graphql 17.0.2 (latest-16 = 16.14.2), @graphql-codegen/cli 7.2.0, @graphql-codegen/client-preset 6.1.2. Apollo Client 4 (4.0.0, released 2025-08-21) changed enough to invalidate most v3 muscle memory: useQuery also returns dataState ("empty" | "partial" | "streaming" | "complete"), which narrows data without optional chaining. A migration codemod exists: npx @apollo/client-codemod-migrate-3-to-4 src. useMutation returns a tuple, not the object useQuery gives you — the single most common mix-up when writing a first write against a codebase you have only read queries in: