TanStack Query Patterns

TanStack Query Patterns

This skill enforces TanStack Query best practices for server state management in React applications.

Query Key Factory Pattern

The factory pattern provides type-safe, hierarchical query keys:

// lib/query-keys.ts
export const queryKeys = {
  posts: {
    all: () => ['posts'] as const,
    lists: () => [...queryKeys.posts.all(), 'list'] as const,
    list: (filters: PostFilters) => [...queryKeys.posts.lists(), filters] as const,
    details: () => [...queryKeys.posts.all(), 'detail'] as const,
    detail: (id: string) => [...queryKeys.posts.details(), id] as const,
    comments: (id: string) => [...queryKeys.posts.detail(id), 'comments'] as const,
  },
  users: {
    all: () => ['users'] as const,
    detail: (id: string) => [...queryKeys.users.all(), id] as const,
    profile: () => [...queryKeys.users.all(), 'profile'] as const,
  },
  auth: {
    session: () => ['auth', 'session'] as const,
  },
} as const

Query Options Factory

Define reusable query options for consistency:

// features/posts/queries/postQueries.ts
import { queryOptions } from '@tanstack/react-query'
import { queryKeys } from '@/lib/query-keys'
import { postApi } from '@/features/posts/api'

export const postQueryOptions = (postId: string) =>
  queryOptions({
    queryKey: queryKeys.posts.detail(postId),
    queryFn: () => postApi.getPost(postId),
    staleTime: 5 * 60 * 1000, // 5 minutes
  })

export const postsQueryOptions = (filters: PostFilters = {}) =>
  queryOptions({
    queryKey: queryKeys.posts.list(filters),
    queryFn: () => postApi.getPosts(filters),
    staleTime: 1 * 60 * 1000, // 1 minute
  })

export const postCommentsQueryOptions = (postId: string) =>
  queryOptions({
    queryKey: queryKeys.posts.comments(postId),
    queryFn: () => postApi.getPostComments(postId),
    enabled: Boolean(postId),
  })

Query Client Setup

// lib/query-client.ts
import { QueryClient } from '@tanstack/react-query'

export function createQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 60 * 1000, // 1 minute
        gcTime: 5 * 60 * 1000, // 5 minutes (formerly cacheTime)
        retry: 1,
        refetchOnWindowFocus: false,
      },
      mutations: {
        retry: 0,
      },
    },
  })
}