AGENT SKILL

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

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

  1. Create or extend src/services/<domain>/queryKeys.ts — hierarchical key factory
  2. Create or extend src/services/<domain>/queries.ts — queryOptions/mutationOptions factories
  3. Create or extend src/services/<domain>/api.ts — typed API functions using http/httpPrivate
  4. Consume in components via useSuspenseQuery (default) — fall back to useQuery only when enabled is needed; if you need to keep previous data during key changes, use startTransition (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 in queries.ts
  • [ ] Handle onSuccess — invalidate or update related queries via { client } context arg
  • [ ] Consume with useMutation in component

Adding optimistic updates

  • [ ] Use useOptimisticMutation hook from src/hooks/useOptimisticMutation.ts
  • [ ] Provide queryKey, updater, and invalidates array
  • [ ] 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

Phenomenon-Studio
Phenomenon-Studio/phenomenon-configs

web-security

Enforce web security and avoid security vulnerabilities.

★ 1
Phenomenon-Studio
Phenomenon-Studio/phenomenon-configs

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.

★ 1
Phenomenon-Studio
Phenomenon-Studio/phenomenon-configs

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.

★ 1
Phenomenon-Studio
Phenomenon-Studio/phenomenon-configs

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.

★ 1
Phenomenon-Studio
Phenomenon-Studio/phenomenon-configs

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.

★ 1
Phenomenon-Studio
Phenomenon-Studio/phenomenon-configs

react

Build clean, modern React components that apply common best practices and avoid common pitfalls like unnecessary state management or useEffect usage.

★ 1