docs: add handoff for TanStack Router + Query migration

[chiptus]

Co-Authored-By: Claude Opus 4.8 (1M context) noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_01CZqUFo6ufUPzXdXb1SssPb

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
upline	Ready	Preview, Comment	Jun 24, 2026 4:06pm

[qodo-code-review]

PR Summary by Qodo

Docs: handoff plan for TanStack Router + Query migration patterns
📝 Documentation 🕐 10-20 Minutes

Description

• Document a phased plan to adopt queryOptions, loader ensureQueryData, and useSuspenseQuery.
• Capture current repo state, target end-state, and a recommended pilot “vertical slice”.
• Call out codebase-specific caveats (auth context, conditional queries, rewrites) to avoid
 missteps.

Diagram

graph TD
  A["TanStack Router"] --> B["Route loaders"] --> C["queryClient.ensureQueryData"] --> D[("TanStack Query cache")] --> E["useSuspenseQuery"]
  B --> F["Pending/Error UI"]
  G["Phase 0: Factories"] --> H["Phase 1: Pilot slice"] --> I["Phase 2: Rollout"] --> J["Phase 3: Cleanup"]
  E --> J
  subgraph Legend
    direction LR
    _fw["Framework/Library"] ~~~ _step["Migration step"] ~~~ _data[("Cache/Data")]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Loader-only prefetch (keep useQuery)

• ➕ Simpler migration; avoids suspense-specific ergonomics and error boundaries.
• ➕ Works better with conditional/enabled queries and auth-dependent data.
• ➖ Leaves duplication risk if query definitions remain split across hooks/loaders.
• ➖ Doesn’t get non-nullable data guarantees and simplified UI logic from suspense.

2. Big-bang refactor per domain (convert everything at once)

• ➕ Faster convergence to a consistent pattern; fewer mixed paradigms during the transition.
• ➖ High risk of import cycles, routing regressions, and hard-to-debug cache behavior.
• ➖ Large review surface area; harder to validate preload/error handling incrementally.

3. Centralize all query factories in a single shared module

• ➕ Single obvious place to find query definitions; avoids feature scattering.
• ➖ Conflicts with the repo’s “no barrels”/direct imports ethos and grows a monolith.
• ➖ Increases coupling across features and raises chance of accidental import cycles.

Recommendation: The phased, vertical-slice-first approach in this handoff is the best fit: it de-risks import-cycle decisions (types.ts vs api.ts placement for fetchers), validates loader prefetch + suspense ergonomics in one end-to-end path, and allows you to explicitly exclude auth-dependent/conditional queries early. The main adjustment to watch is enforcing a clean module boundary for fetchX functions to avoid types.ts↔hook circular imports.

Files changed (1) +203 / -0

Documentation (1) +203 / -0

HANDOFF_TANSTACK_ROUTER_QUERY.mdAdd detailed migration handoff for Router+Query best practices +203/-0

Add detailed migration handoff for Router+Query best practices

• Introduces a plan-only handoff document to standardize TanStack Router + TanStack Query integration. Describes current state, phased rollout (factories → pilot → feature rollout → cleanup), and repo-specific caveats like auth context availability in loaders and conditional query handling.

docs/HANDOFF_TANSTACK_ROUTER_QUERY.md

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review