tanstack-query
TanStack Query patterns for this repo — queryOptions/mutationOptions factories, query key hierarchies, service layer integration, optimistic updates, Suspense usage, error handling, and TanStack Router data loading. Use when creating queries, mutations, API services, query keys, cache invalidation, optimistic updates, or integrating data fetching with routes.
- License 许可
- MIT
- 最近更新
- 2026-10-23
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- tanstack-query
- description
- TanStack Query patterns for this repo — queryOptions/mutationOptions factories, query key hierarchies, service layer integration, optimistic updates, Suspense usage, error handling, and TanStack Router data loading. Use when creating queries, mutations, API services, query keys, cache invalidation, optimistic updates, or integrating data fetching with routes.
- user-invocable
- false
02 资源文件 1
- 参考文档REFERENCE.md21.7 KB
03 SKILL.md 正文
TanStack Query
Quick start
This repo uses TanStack Query v5 with strict ESLint rules (flat/recommended-strict). Data fetching is organized per service domain in src/services/<domain>/.
Adding a new query
- Create or extend
src/services/<domain>/queryKeys.ts— hierarchical key factory - Create or extend
src/services/<domain>/queries.ts—queryOptions/mutationOptionsfactories - Create or extend
src/services/<domain>/api.ts— typed API functions usinghttp/httpPrivate - Consume in components via
useSuspenseQuery(default) — fall back touseQueryonly whenenabledis needed; if you need to keep previous data during key changes, usestartTransition(see REFERENCE.md § Suspense-First Approach)
// queries.ts
import { queryOptions } from '@tanstack/react-query';
import { fetchPosts } from './api';
import { postsKeys } from './queryKeys';
export const postsListQueryOptions = (filters?: PostFilters) => {
return queryOptions({
queryKey: postsKeys.listQueryKey(filters),
queryFn: () => fetchPosts(filters),
});
};
Workflows
Adding a new service domain
- [ ] Create
src/services/<domain>/types.ts— request/response types - [ ] Create
src/services/<domain>/api.ts— API functions - [ ] Create
src/services/<domain>/queryKeys.ts— key factory - [ ] Create
src/services/<domain>/queries.ts— query/mutation options - [ ] Wire into route loader or component
Adding a mutation with cache invalidation
- [ ] Add mutation key to
queryKeys.ts(if needed for optimistic updates) - [ ] Create
mutationOptions()factory inqueries.ts - [ ] Handle
onSuccess— invalidate or update related queries via{ client }context arg - [ ] Consume with
useMutationin component
Adding optimistic updates
- [ ] Use
useOptimisticMutationhook fromsrc/hooks/useOptimisticMutation.ts - [ ] Provide
queryKey,updater, andinvalidatesarray - [ ] See REFERENCE.md § Optimistic Updates
Key conventions
| Pattern | This repo's approach |
|---|---|
| Query options | Always use queryOptions()/mutationOptions() factories — never inline config |
| Query keys | Hierarchical factory per domain with as const; methods, not plain properties |
| API functions | Typed wrappers around http/httpPrivate (ky) in api.ts |
| Imperative fetch | Only queryClient.query()/queryClient.infiniteQuery(). Loaders/beforeLoad: spread staleTime: 'static' (cache-or-fetch). Fire-and-forget: .catch(noop) — query() rejects. ensureQueryData/fetchQuery/prefetchQuery/fetchInfiniteQuery/prefetchInfiniteQuery/ensureInfiniteQueryData are deprecated (removed in v6) |
| Query hooks | Suspense-first: prefer useSuspenseQuery/useSuspenseQueries/useSuspenseInfiniteQuery; only fall back to useQuery/useQueries when enabled is required |
| Error handling | Global QueryCache.onError for toasts; throwOnError: true for boundaries |
| Error type | Registered globally as HTTPError<BaseErrorData> |
| Data transforms | Use select option, not inline transforms in queryFn |
| Mutations context | Access client (QueryClient) via 4th arg in callbacks: onSuccess(data, vars, onMutateResult, { client }) |
| Import order | Follow Prettier import sorting — types first, then @tanstack, then local |
Advanced features
See REFERENCE.md for detailed patterns:
- Service layer architecture (api, queryKeys, queries)
- Query key factory design
- QueryClient configuration and error registration
- Optimistic mutations (useOptimisticMutation hook)
- Imperative QueryClient API (
query/infiniteQuery,staleTime: 'static', deprecated → replacement table) - TanStack Router integration (loaders, prefetching, loaderDeps)
- Error handling strategies
- Dependent and parallel queries
- Infinite queries
- Data transformations with
select - Cache invalidation strategies
04 同仓库更多 Skills
web-security
Enforce web security and avoid security vulnerabilities.
typescript
Write clean, efficient TypeScript code that follows project conventions and advanced type patterns. Use when writing or reviewing TypeScript code, defining types, creating generics, handling errors, or working with React components, Zod schemas, and TanStack libraries.
tanstack-router
TanStack Router patterns for this repo — file-based routing, auth guards, search params, data loading, TanStack Query integration, navigation, and code splitting. Use when creating routes, adding pages, implementing auth flows, working with search/path params, or integrating loaders with TanStack Query.
tanstack-query
TanStack Query patterns for this repo — queryOptions/mutationOptions factories, query key hierarchies, service layer integration, optimistic updates, Suspense usage, error handling, and TanStack Router data loading. Use when creating queries, mutations, API services, query keys, cache invalidation, optimistic updates, or integrating data fetching with routes.
tanstack-form
Build forms using TanStack Form with the project's useAppForm composition, composable field components, Zod validation schemas, FormFieldWrapper error tracking, and form.AppField vs form.Field patterns. Use when creating new forms, adding form fields, writing form validation, or working with TanStack Form in this project.
react
Build clean, modern React components that apply common best practices and avoid common pitfalls like unnecessary state management or useEffect usage.