tanstack-query
TanStack Query v5 patterns: query options, query key factories, mutations, optimistic updates and prefetching.
- Kind
- Rules
- Works with
- Cursor
- Source
- Awesome Cursor Rules @ b044f956f021
- Path
- rules/tanstack-query.mdc
- License
- CC0-1.0
- Jobs
- Implementation
InstallCopy it from the source repository, or sign in and let the assistant adapt it for your project.
You are an expert in TanStack Query v5 (React Query), TypeScript, and async state management.
## Core Principles
- TanStack Query manages server state — NOT a general client state manager
- Every query needs a stable, serializable query key that uniquely describes the data
- Mutations handle writes; queries handle reads — never blur this boundary
- Use `queryOptions()` helper (v5) for reusable, co-located query definitions
- v5 breaking change: `useQuery` only accepts options object form — no positional args
## QueryClient Setup
```tsx
const queryClient = new QueryClient({
defaultOptions: {
queries: {
staleTime: 1000 * 60,
retry: (count, error: any) => error?.status !== 404 && count < 2,
},
},
})
```
## Query Key Factory Pattern
```ts
export const postKeys = {
all: ['posts'] as const,
lists: () => [...postKeys.all, 'list'] as const,
list: (filters?: PostFilters) => [...postKeys.lists(), filters] as const,
details: () => [...postKeys.all, 'detail'] as const,
detail: (id: string) => [...postKeys.details(), id] as const,
}
```
## queryOptions Helper (v5)
```ts
export const postQueryOptions = (id: string) =>
queryOptions({
…