calypso-react-query-migration

Calypso React Query Migration

Target architecture: fetchers in @automattic/api-core → query/mutation options in @automattic/api-queries → components call useQuery() / useMutation() directly.

Two source patterns migrate into it:

1. Redux data-layer (dispatchRequest + http actions in client/state/data-layer/wpcom/read/)
2. @automattic/data-stores Reader hooks (custom hooks using wpcomRequest)

Quick Reference: Where Things Go

Naming conventions (must follow)

Every Reader fetcher / query / mutation / response type carries the Read prefix — the rest of api-core and api-queries does this consistently and breaking the pattern stands out in code review.

Workflow (Required)

digraph migration_flow {
    "Migration request" [shape=doublecircle];
    "Audit CRUD + existing fetchers" [shape=box];
    "Write plan" [shape=box];
    "Bridge decision"

Always plan before editing. A one-line request like "migrate QueryReaderTag" is a spec — turn it into a plan first.

REQUIRED SUB-SKILLS:

• superpowers:writing-plans — to draft the plan
• superpowers:executing-plans — to execute it with checkpoints

The plan must include: full CRUD audit, bridge decision (with reason), commit split, per-mutation invalidations + optimistic-update decision, list of consumers to update, test plan.

Save the plan to .context/plan-migrate-reader-{name}.md.

Step 1: Audit before writing

CRUD coverage

List every action for the resource — read AND mutations. Partial migrations create two sources of truth (deleted item still shows in sidebar until refresh).

Plan one commit per action group; each commit removes its Redux counterpart (mutations don't need a bridge).

Existing api-core fetchers

Don't duplicate. Grep before creating:

If a fetcher exists: reuse (import from @automattic/api-core) or extend (add to existing folder, not a parallel one).

Cache-key consumers (mandatory check)

Before changing or replacing a query key, find every other piece of code reading or writing it. Mutations and shared helpers commonly do optimistic setQueryData / invalidateQueries against the old key — change the key without updating them and they silently no-op, leaving the user looking at stale data after every action.

For every match, decide:

• Update to the new key (preferred — small follow-up patch in the same PR, or co-located mutation migration).
• Migrate the consumer too (when it's a mutation that should join this migration anyway).
• Bridge (last resort: keep the old key alive in parallel until the consumer is migrated).

Document the decision per match in the plan. The trap: when the only consumer of the old key is a mutation's optimistic write, deleting the data-stores hook looks clean — grep for the hook name finds nothing — but the mutation still operates on a phantom cache that no live query reads, and the visible page never updates after the user acts.

Step 2: Bridge decision

The QueryReader* bridge dispatches RECEIVE so the rest of Calypso keeps reading from Redux. It's not the long-term target. Evaluate removing it in this migration before defaulting to keeping it.

Record the decision verbatim in the plan. When removing the bridge, grep to confirm nothing else reads RECEIVE/reducer/selectors before deleting them.

Step 3: Build the migration

Create the fetcher (api-core)

Find method, path, apiVersion, and query/body in the existing data-layer http() call. Copy exactly. Always import wpcom from ../wpcom-fetcher (not directly).

Add types in types.ts, barrel-export from index.ts, then export the module from packages/api-core/src/index.ts.

Subkey-auth fallback (logged-out subscription-management endpoints)

Some Reader endpoints (/read/sites/{blogId}/subscription-details, /read/subscriptions/{id}, anything reachable from the public /subscriptions/... landing pages) accept logged-out callers via an X-WPSUBKEY header. The legacy data-stores callApi helper handles this; wpcom.req.get does not, because wpcom-proxy-request requires a session.

Trigger: the source hook calls callApi with an isLoggedIn arg, or imports getSubkey, or the consumer renders under a /subscriptions/... route.

Before designing the fork, confirm with backend:

• Does the endpoint accept both cookie auth and X-WPSUBKEY?
• If both arrive, which wins? (Calypso ships the cookie unconditionally for logged-in users, so the answer affects whether the subkey path is safe to take preemptively.)
• When is window.currentUser.subscriptionManagementSubkey populated? (Today: only the logged-out subscriptions bootstrap.)

Pattern when both auth modes are accepted and cookie wins server-side — the bifurcation becomes pure transport, not URL or auth strategy:

Use raw fetch rather than @wordpress/api-fetch — avoids adding the dep to api-core and the subkey path needs none of apiFetch's middleware. The client/lib/request-with-subkey-fallback/ helper does the same thing for non-Reader code, but don't import it from api-core (wrong direction); inline the logic.

Create the query options (api-queries)

queryKey: ['read', '{domain}', ...params]. staleTime: ~1min for data with external change events (payments, renewals, server-side mutations), ~5min for slowly-changing lists. Confirm change-rate with backend when unsure. enabled: when params can be null.

When migrating from data-stores, preserve the same queryKey for cache compatibility mid-session.

Bridge component (only if kept)

If the legacy code dispatched success/failure actions, mirror both via isSuccess / isError effects.

Tests

See test-scaffolding.md for the full template (createTestStore, renderWithProviders, nock setup).

nock URL: https://public-api.wordpress.com/rest/v{apiVersion}/{path} for wpcom.req.get calls, https://public-api.wordpress.com/wpcom/v2{path} for apiNamespace: 'wpcom/v2' v2 calls. Run with yarn test-client client/components/data/query-reader-{name}/test/.

Mutations

See mutations.md — covers mutators, mutationOptions, cache invalidation rules, optimistic updates (default for user-facing mutations), and where side effects live (consumer's onSuccess, not api-queries).

Migrating from data-stores

Same fetcher/query pattern, with two differences:

• No bridge needed — the consumer already uses React Query; just swap the import.
• Single commit — no Redux cleanup.

After updating consumers, delete the hook from packages/data-stores/src/reader/queries/ and remove its export from the Reader barrel.

Step 4: Clean up Redux

Read redux-cleanup.md for: per-action checklist, replacing isRequesting* selectors with React Query state, function-component connect() → hooks conversion, and the class-component HOC pattern.

Cleanup is a separate commit from the migration commit — easier to review and revert.

Red Flags — STOP

If you catch yourself doing any of these, stop and reconsider:

• About to edit api-core, api-queries, client/components/data/query-reader-*, or Redux Reader state without a written plan → write the plan first.
• About to migrate only the read query while leaving CREATE/UPDATE/DELETE in Redux → finish the CRUD audit first.
• About to create packages/api-core/src/read-{name}/ without grepping for an existing module → check api-core first.
• About to delete an isRequesting* selector or RECEIVE reducer without grepping for consumers → grep first.
• About to write a mutation with only invalidateQueries and no onMutate for a user-facing action → consider optimistic updates.
• About to put navigation / notice dispatch inside the mutation's onSuccess in api-queries → side effects belong in the consumer's onSuccess.
• About to rewrite a class component to a function component as part of this migration → out of scope; use an HOC instead.
• About to change the queryKey when migrating from data-stores → preserve it for mid-session cache compatibility.
• About to delete or rename a query key without grepping for every consumer (mutations, optimistic-update helpers, selectors, other queries that prefix-invalidate it) → grep first; mutations referencing a now-orphan key silently no-op and the visible page stops updating after user actions.

Common Mistakes