Skill: tanstack-query

Scope

• Applies to: TanStack Query v5+ for async operations, data fetching, caching, mutations, infinite queries, optimistic updates

• Does NOT cover: URL state management (use nuqs), grouped synchronous state (use ahooks.useSetState), localStorage persistence (use ahooks.useLocalStorageState)

Assumptions

• TanStack Query v5+

• React 18+ with hooks support

• TypeScript v5+ (for type inference)

• @lukemorales/query-key-factory for query key management

• QueryClientProvider configured at app root

Principles

• Use TanStack Query for ANY async operation that benefits from caching or state management

• Query key factory pattern for centralized, type-safe query keys

• Never manually manage isLoading , error , or isError states (provided by hooks)

• queryFn can be any Promise-returning function (not just HTTP calls)

• All TanStack features work identically regardless of data source: caching, deduping, background refetching, stale-while-revalidate

Constraints

MUST

• Use query key factory (@lukemorales/query-key-factory ) for all query keys

• Use TanStack Query hooks for async operations (never manually manage loading/error states)

• Use namespace invalidation: queryClient.invalidateQueries({ queryKey: users._def })

SHOULD

• Use TanStack Query for any async operation that benefits from caching (HTTP, localStorage reads, local computations, file operations)

• Extract query logic into custom hooks for reusability

• Combine multiple queries into cohesive hooks

• Use TypeScript generics for type-safe queries: useQuery<ResponseType>(...)

• Configure QueryClient defaults (retry, staleTime) at provider level

AVOID

• Manually constructing query keys: useQuery({ queryKey: ['users', id] })

• Hardcoding query keys in invalidations: queryClient.invalidateQueries({ queryKey: ['users'] })

• Manually managing loading/error states (use hook-provided states)

• Using for URL-shareable state (use nuqs instead)

• Using for grouped synchronous state (use ahooks.useSetState instead)

• Using for one-off promises without caching needs (use plain async/await in event handlers)

Interactions

• Complements nuqs for URL state management (queries can depend on URL params)

• Complements ahooks for synchronous state (useSetState for form state, useLocalStorageState for persistence)

• Works with generated API clients from OpenAPI specs (@repo/react)

• Part of state management decision tree (see React rules)

Patterns

Query Key Factory Pattern

Centralized, type-safe query keys:

import { createQueryKeys } from '@lukemorales/query-key-factory'

export const users = createQueryKeys('users', { detail: (id: string) => ({ queryKey: [id], queryFn: () => fetchUser(id), }), list: (filters?: Filters) => ({ queryKey: [filters], queryFn: () => fetchUsers(filters), }), })

// Usage import { useQuery } from '@tanstack/react-query' import { users } from '@/queries/users'

const { data, isLoading, error } = useQuery(users.detail(userId))

File Organization: src/queries/users.ts

• Query key factory for users, src/queries/articles.ts
• Query key factory for articles, src/queries/index.ts
• Re-export all query keys

Versatile queryFn Pattern

TanStack Query accepts ANY async queryFn —not just HTTP calls:

// Server data fetching (traditional) const { data } = useQuery({ queryKey: ['users', userId], queryFn: () => fetchUser(userId), })

// Local computation (no network) const { data } = useQuery({ queryKey: ['fibonacci', n], queryFn: () => computeFibonacci(n), })

// localStorage read const { data: settings } = useQuery({ queryKey: ['user-settings'], queryFn: () => Promise.resolve( JSON.parse(localStorage.getItem('settings') || '{}') ), })

// File operation const { data } = useQuery({ queryKey: ['file-content', path], queryFn: () => readFile(path), })

When to use: Any async operation that benefits from automatic caching, stale management, or repeated execution

When NOT to use: One-off promises without caching needs (use plain async/await in event handlers)

Mutation Pattern

Mutations with automatic invalidation:

import { useMutation, useQueryClient } from '@tanstack/react-query' import { users } from '@/queries/users'

function useCreateUser() { const queryClient = useQueryClient()

return useMutation({ mutationFn: async (data: CreateUserInput) => { const response = await createUser(data) return response }, onSuccess: () => { // Namespace invalidation (recommended) queryClient.invalidateQueries({ queryKey: users._def }) }, }) }

// Usage const createUser = useCreateUser() createUser.mutate({ name: 'John', email: 'john@example.com' })

Infinite Query Pattern

Pagination with infinite scroll:

import { useInfiniteQuery } from '@tanstack/react-query' import { users } from '@/queries/users'

const { data, fetchNextPage, hasNextPage, isFetchingNextPage, } = useInfiniteQuery({ queryKey: ['users', 'infinite'], queryFn: ({ pageParam = 0 }) => fetchUsers({ page: pageParam }), getNextPageParam: (lastPage, pages) => lastPage.nextPage, initialPageParam: 0, })

QueryClient Configuration

Configure defaults at provider level:

import { QueryClient, QueryClientProvider } from '@tanstack/react-query' import { useState } from 'react'

function Providers({ children }: { children: ReactNode }) { const [queryClient] = useState(() => new QueryClient({ defaultOptions: { queries: { staleTime: 60 * 1000, // 1 minute retry: 1, refetchOnWindowFocus: false, }, }, }))

return ( <QueryClientProvider client={queryClient}> {children} </QueryClientProvider> ) }

Generated API Client Integration

Use generated hooks from OpenAPI specs:

import { useHealthCheck } from '@repo/react'

function HealthStatus() { const { data, isLoading, error } = useHealthCheck()

if (isLoading) return <div>Loading...</div> if (error) return <div>Error: {error.message}</div>

return <div>Status: {data.status}</div> }

Custom Hook Pattern

Extract query logic into reusable hooks:

// hooks/useUser.ts import { useQuery } from '@tanstack/react-query' import { users } from '@/queries/users'

export function useUser(userId: string) { return useQuery(users.detail(userId)) }

// Component usage function UserProfile({ userId }: { userId: string }) { const { data: user, isLoading, error } = useUser(userId) // ... }

State Management Decision Tree

• URL-shareable state → Use nuqs (filters, search, tabs, pagination)

• Grouped state not in URL → Use ahooks.useSetState (form state, game engine, ephemeral UI)

• Async operations → Use TanStack Query (data fetching, mutations, caching)

• localStorage persistence → Use ahooks.useLocalStorageState (preferences, settings)

• Simple independent state → Use useState (rare, prefer other options)

Use TanStack Query for: Server data fetching, mutations, optimistic updates, background refetching, caching, any async operation that benefits from state management

Don't use TanStack Query for: URL-shareable state (use nuqs), grouped synchronous state (use ahooks.useSetState), one-off promises without caching needs

References

• TanStack Query documentation - Official documentation

• Query Key Factory - Query key factory library

• React rules - State management decision tree and patterns

• ahooks - Utility hooks for synchronous state

• OpenAPI Integration - Generated client patterns