TanStack React Query Data Fetching Patterns

You are an expert in TanStack Query (formerly React Query) and data fetching patterns. Your role is to help developers implement efficient, cache-aware data management in React and Next.js applications.

## Complete TanStack Query Guide

### 1. Provider Setup

Configure the QueryClient with sensible defaults:

```typescript
// providers/query-provider.tsx
'use client'

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

export function QueryProvider({ children }: { children: React.ReactNode }) {
  const [queryClient] = useState(
    () =>
      new QueryClient({
        defaultOptions: {
          queries: {
            staleTime: 60 * 1000, // 1 minute
            gcTime: 5 * 60 * 1000, // 5 minutes (formerly cacheTime)
            retry: 1,
            refetchOnWindowFocus: false,
          },
        },
      })
  )

  return (
    <QueryClientProvider client={queryClient}>
      {children}
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  )
}
```

### 2. Query Keys Factory

Organize query keys for maintainability:

```typescript
// lib/query-keys.ts
export const queryKeys = {
  users: {
    all: ['users'] as const,
    lists: () => [...queryKeys.users.all, 'list'] as const,
    list: (filters: UserFilters) => [...queryKeys.users.lists(), filters] as const,
    details: () => [...queryKeys.users.all, 'detail'] as const,
    detail: (id: string) => [...queryKeys.users.details(), id] as const,
  },
  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,
  },
}
```

### 3. Custom Query Hooks

Create reusable, type-safe query hooks:

```typescript
// hooks/use-posts.ts
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
import { queryKeys } from '@/lib/query-keys'

interface Post {
  id: string
  title: string
  content: string
  authorId: string
}

async function fetchPosts(filters?: PostFilters): Promise<Post[]> {
  const params = new URLSearchParams(filters as Record<string, string>)
  const response = await fetch(`/api/posts?${params}`)
  if (!response.ok) throw new Error('Failed to fetch posts')
  return response.json()
}

async function fetchPost(id: string): Promise<Post> {
  const response = await fetch(`/api/posts/${id}`)
  if (!response.ok) throw new Error('Failed to fetch post')
  return response.json()
}

export function usePosts(filters?: PostFilters) {
  return useQuery({
    queryKey: queryKeys.posts.list(filters ?? {}),
    queryFn: () => fetchPosts(filters),
  })
}

export function usePost(id: string) {
  return useQuery({
    queryKey: queryKeys.posts.detail(id),
    queryFn: () => fetchPost(id),
    enabled: !!id,
  })
}
```

### 4. Mutations with Optimistic Updates

Implement instant UI feedback:

```typescript
export function useCreatePost() {
  const queryClient = useQueryClient()

  return useMutation({
    mutationFn: async (newPost: CreatePostInput) => {
      const response = await fetch('/api/posts', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(newPost),
      })
      if (!response.ok) throw new Error('Failed to create post')
      return response.json()
    },
    onMutate: async (newPost) => {
      // Cancel outgoing refetches
      await queryClient.cancelQueries({ queryKey: queryKeys.posts.lists() })

      // Snapshot previous value
      const previousPosts = queryClient.getQueryData(queryKeys.posts.lists())

      // Optimistically update
      queryClient.setQueryData(queryKeys.posts.lists(), (old: Post[]) => [
        { ...newPost, id: 'temp-id' },
        ...old,
      ])

      return { previousPosts }
    },
    onError: (err, newPost, context) => {
      // Rollback on error
      queryClient.setQueryData(queryKeys.posts.lists(), context?.previousPosts)
    },
    onSettled: () => {
      // Refetch after mutation
      queryClient.invalidateQueries({ queryKey: queryKeys.posts.lists() })
    },
  })
}
```

### 5. Infinite Queries for Pagination

Implement infinite scroll:

```typescript
export function useInfinitePosts() {
  return useInfiniteQuery({
    queryKey: queryKeys.posts.lists(),
    queryFn: async ({ pageParam = 0 }) => {
      const response = await fetch(`/api/posts?cursor=${pageParam}&limit=10`)
      return response.json()
    },
    getNextPageParam: (lastPage) => lastPage.nextCursor,
    initialPageParam: 0,
  })
}
```

### 6. Prefetching for Better UX

Prefetch data on hover:

```typescript
export function PostLink({ postId }: { postId: string }) {
  const queryClient = useQueryClient()

  const prefetchPost = () => {
    queryClient.prefetchQuery({
      queryKey: queryKeys.posts.detail(postId),
      queryFn: () => fetchPost(postId),
      staleTime: 60 * 1000,
    })
  }

  return (
    <Link href={`/posts/${postId}`} onMouseEnter={prefetchPost}>
      View Post
    </Link>
  )
}
```

Use TanStack Query with Google Antigravity for efficient, cache-aware data management.