refactor(frontend): replace Apollo Client with urql for the GraphQL transport [INFP-563]

Merged
BI
4mo ago
+874-1051

What & why

The frontend used @apollo/client as a transport-only GraphQL layer — no Apollo hooks, no Apollo cache (fetchPolicy: "no-cache", queryDeduplication: false), no subscriptions. TanStack Query is and remains the sole caching and request-deduplication authority. Apollo was paying for a cache and a hooks layer the app never used.

This replaces it with @urql/core + @urql/exchange-auth, keeping the imperative graphqlClient.query() / graphqlClient.mutate() interface so the ~95 call sites are untouched by design.

Dependencies: -@apollo/client, -apollo-upload-client, -@types/apollo-upload-client, +@urql/core, +@urql/exchange-auth.

Bundle: 4,574,160 → 4,539,212 bytes gzipped JS (−34,948 bytes, ≈ −34 KB), measured by summing gzipped dist/assets/*.js across a production build on the same machine.

No user-facing behaviour change. Auth, priority header, error routing, token refresh-and-replay, and file uploads are all preserved.

Notable implementation details

Four places where urql's defaults differ from Apollo's and parity had to be restored deliberately:

preferGetMethod: false — urql's within-url-limit default sends small queries as GET, which the backend's /graphql answers with the SPA fallback index.html. Forced to POST, with a regression test.

__typename injection — Apollo's InMemoryCache added it automatically and several dynamic object queries relied on it. Restored with a mapExchange running formatDocument.

One urql client per endpoint — this is the subtle one. urql's Client merges concurrent operations by hash(query, variables) and ignores the URL, but this app carries branch and point-in-time in the URL. A single shared client therefore served one branch's data to both callers of two concurrent identical queries on different branches — a branch-safety hazard, not a caching nicety. getGraphqlClient(branch, date) memoises a client per endpoint, so each branch/date keeps its own in-flight operations. Verified against @urql/core directly: with one shared client the two-branch case produces 1 fetch and identical data for both callers; with per-endpoint clients it produces 2, each correct. Same-endpoint identical queries still share one request, as before.

Error routing — handleGraphQLErrors keeps the catalogue-code routing (TOKEN_EXPIRED / AUTHENTICATION_REQUIRED → /login, PERMISSION_DENIED silent, generic → the caller's processErrorMessage). Both network and GraphQL errors reject, so a resolved result carries data only — every use-case already threw on errors, and the ones that did not dereferenced null.

The transport also dropped things that turned out to be dead: the X-Priority header is a client-level constant (no call site ever overrode it), and GraphQLRequestContext.date is now Date | null (nothing ever passed a string).

Testing

  • pnpm test — 1096 passing (159 files), including new regression tests for POST-not-GET, __typename injection, endpoint targeting, the priority header, the refresh-and-replay contract (one refresh, one replay, then bail), cross-branch / cross-date concurrent operations, the multipart shape of a File upload, and X-Priority surviving the replayed operation after a refresh. The last two cover guarantees that rest entirely on @urql/* internals and had no fast-suite coverage.
  • pnpm exec biome ci . — clean.
  • pnpm knip — clean.
  • pnpm build — succeeds.
  • pnpm exec betterer ci — clean (190 issues, unchanged).

🤖 Generated with Claude Code