tanstack-query-integration

将 TanStack Query 与 oRPC 集成，用于数据获取、数据变更以及乐观更新。本技能分为查询、变更、缓存及最佳实践等专题参考指南。适用于创建查询钩子、管理数据变更、实施乐观更新、执行缓存失效操作，或与路由加载器集成时使用。

name: tanstack-query-integration description: Integrate TanStack Query with oRPC for data fetching, mutations, and optimistic updates. Divided into focused reference guides for queries, mutations, caching, and best practices. Use when creating query hooks, managing mutations, optimistic updates, cache invalidation, or integrating with route loaders.

TanStack Query Integration

Modular guides for integrating TanStack Query with oRPC for type-safe, performant data fetching and state management.

Core Concepts

The web app uses tanstackRPC (from @~/utils/tanstack-orpc.ts) which applies createTanstackQueryUtils to the oRPC client. Every contract procedure gets:

•.queryOptions() - Query configuration
•.mutationOptions() - Mutation configuration
•.queryKey() - Type-safe query key generation
•.call() - Direct procedure call

Quick Reference

Guide	Use When
Query Hooks	Creating hooks for data fetching, exporting query options
Mutation Hooks	Implementing mutations with cache invalidation
Optimistic Updates	Making UI instant with optimistic cache updates
Cache Invalidation	Keeping data fresh after mutations
Route Integration	Prefetching data in route loaders
Loading States	Handling loading, error, and empty states
Best Practices	10 critical best practices to follow

Learning Path

Beginner: Start with Query Hooks → Mutation Hooks → Loading States
Intermediate: Add Optimistic Updates → Cache Invalidation
Advanced: Route Integration → Best Practices

TanStack Query Integration

Core Concepts

Quick Reference

Learning Path

See Also