docs(client): urql client review findings and remediation blueprint

[gilgardosh]

Draft, for tracking and reference only — not intended to merge.

This PR is not part of the implementation stack. It holds the review and the plan in one place so the per-step PRs have something to link back to.

What's here

• docs/urql-client-review/findings.md — the review itself. 127 useQuery call sites, 104 useMutation call sites, 318 GraphQL documents across 294 files.
• docs/urql-client-review/blueprint.md — the phased remediation plan, with a status table tracking each step's PR.

The headline finding

packages/client/src/providers/urql.tsx:230 constructs the client with an explicit exchanges array:

mapExchange (global error toast)  ->  authExchange  ->  fetchExchange

urql installs its default [cacheExchange, fetchExchange] only when exchanges is omitted entirely. Because an explicit array is supplied and cacheExchange is absent, the app runs with no document cache and no normalized cache — every mount is a network round-trip.

Most other findings are hand-rolled substitutes for that missing cache:

Substitute	Location	Size
onChange prop-drilling	64 declarations across 60 files, 262 pass-downs	the dominant pattern
Charge-id → refetch registry	providers/charge-refresh.tsx	~100 lines reimplementing additionalTypenames
Manual network-only re-execution	25 sites	leaks OperationContext into 3 components' props
Deep-equality reference shims	use-stable-value.ts, per-row JSON.stringify in charges-row.tsx	urql returns a fresh data object per fetch

additionalTypenames is used 0 times — it does nothing without a cache. TODO: add local data update method after change appears 72 times in src/hooks/.

What the codebase gets right

Worth recording, because the fundamentals are strong: codegen client-preset with fragment masking on and genuinely colocated fragments, 100% mutation-hook discipline (zero useMutation in components/), @defer in production, a real N+1 fix in the charges table, and multipart uploads working with no extra configuration.

Planned sequence

Ten steps, each its own PR, stacked while the previous is unmerged. Steps 1–7 change no dependencies and need no yarn generate. The agreed direction for the follow-up phase is @urql/exchange-graphcache (normalized), not a document cache.

Notes

• Documentation only — no package or source changes.
• Four claims from the original review were corrected during blueprinting after verification against the code; the docs reflect the verified state. Most notably: 10 hooks have render-body toasts (not 12), the "7 component-level occurrences" do not exist, no route declares an id, and contracts.tsx has no loader wired at all.

🤖 Generated with Claude Code

https://claude.ai/code/session_01TbrGL3NndzRiEwJkwHxnbm

---

Generated by Claude Code

[github-actions]

The latest changes of this PR are not available as alpha, since there are no linked changesets for this PR.

[Copilot]

🟡 Changes recommended

The new docs include at least one verified incorrect metric (TODO occurrence count) and a small internal inconsistency in Step 0 wording that should be corrected for accuracy.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Documentation-only PR that records an urql usage review for packages/client and a phased remediation blueprint, intended as a single reference point for follow-up implementation PRs.

Changes:

• Added a detailed findings write-up covering current urql client configuration, usage patterns, and observed pain points.
• Added an implementation blueprint with staged steps, verification strategy, and test guidance for the planned remediation sequence.

File summaries

File	Description
docs/urql-client-review/findings.md	Adds the urql client findings report and supporting evidence/metrics.
docs/urql-client-review/blueprint.md	Adds a step-by-step remediation plan with sequencing rationale and verification guidance.

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.