TanStack Query v5 Patterns

# TanStack Query v5 Patterns for Google Antigravity

Master server state management with TanStack Query v5 in your Google Antigravity IDE projects. This comprehensive guide covers queries, mutations, optimistic updates, and caching strategies optimized for Gemini 3 agentic development.

## Query Client Configuration

Set up TanStack Query with proper defaults:

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

export function makeQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 60 * 1000, // 1 minute
        gcTime: 5 * 60 * 1000, // 5 minutes (formerly cacheTime)
        retry: (failureCount, error) => {
          // Don't retry on 4xx errors
          if (error instanceof Response && error.status >= 400 && error.status < 500) {
            return false;
          }
          return failureCount < 3;
        },
        refetchOnWindowFocus: false,
      },
      mutations: {
        retry: false,
      },
    },
  });
}

// Singleton for client-side
let browserQueryClient: QueryClient | undefined = undefined;

export function getQueryClient() {
  if (typeof window === 'undefined') {
    // Server: always make a new query client
    return makeQueryClient();
  }
  // Browser: make a new client if we don't have one
  if (!browserQueryClient) {
    browserQueryClient = makeQueryClient();
  }
  return browserQueryClient;
}
```

## Provider Setup

Configure the query provider for Next.js:

```typescript
// components/providers/QueryProvider.tsx
'use client';

import { QueryClientProvider } from '@tanstack/react-query';
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
import { getQueryClient } from '@/lib/query-client';

export function QueryProvider({ children }: { children: React.ReactNode }) {
  const queryClient = getQueryClient();

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

## Query Patterns

Create type-safe query hooks:

```typescript
// hooks/queries/usePrompts.ts
import { useQuery, useInfiniteQuery, useSuspenseQuery } from '@tanstack/react-query';

// Query key factory for type safety
export const promptKeys = {
  all: ['prompts'] as const,
  lists: () => [...promptKeys.all, 'list'] as const,
  list: (filters: PromptFilters) => [...promptKeys.lists(), filters] as const,
  details: () => [...promptKeys.all, 'detail'] as const,
  detail: (slug: string) => [...promptKeys.details(), slug] as const,
  starred: (userId: string) => [...promptKeys.all, 'starred', userId] as const,
};

interface PromptFilters {
  search?: string;
  category?: string;
  page?: number;
}

// Fetch function
async function fetchPrompts(filters: PromptFilters) {
  const params = new URLSearchParams();
  if (filters.search) params.set('search', filters.search);
  if (filters.category) params.set('category', filters.category);
  if (filters.page) params.set('page', String(filters.page));

  const response = await fetch(`/api/prompts?${params}`);
  if (!response.ok) throw new Error('Failed to fetch prompts');
  return response.json() as Promise<PromptsResponse>;
}

// Basic query hook
export function usePrompts(filters: PromptFilters = {}) {
  return useQuery({
    queryKey: promptKeys.list(filters),
    queryFn: () => fetchPrompts(filters),
    placeholderData: (previousData) => previousData,
  });
}

// Suspense query hook (for React Suspense)
export function usePromptsSuspense(filters: PromptFilters = {}) {
  return useSuspenseQuery({
    queryKey: promptKeys.list(filters),
    queryFn: () => fetchPrompts(filters),
  });
}

// Infinite query for pagination
export function useInfinitePrompts(filters: Omit<PromptFilters, 'page'> = {}) {
  return useInfiniteQuery({
    queryKey: promptKeys.list(filters),
    queryFn: ({ pageParam }) => fetchPrompts({ ...filters, page: pageParam }),
    initialPageParam: 1,
    getNextPageParam: (lastPage) =>
      lastPage.hasMore ? lastPage.page + 1 : undefined,
    getPreviousPageParam: (firstPage) =>
      firstPage.page > 1 ? firstPage.page - 1 : undefined,
  });
}

// Single prompt query
export function usePrompt(slug: string) {
  return useQuery({
    queryKey: promptKeys.detail(slug),
    queryFn: async () => {
      const response = await fetch(`/api/prompts/${slug}`);
      if (!response.ok) {
        if (response.status === 404) {
          throw new NotFoundError('Prompt not found');
        }
        throw new Error('Failed to fetch prompt');
      }
      return response.json() as Promise<Prompt>;
    },
    enabled: Boolean(slug),
  });
}
```

## Mutation Patterns

Implement mutations with optimistic updates:

```typescript
// hooks/mutations/useStarPrompt.ts
import { useMutation, useQueryClient } from '@tanstack/react-query';
import { promptKeys } from '../queries/usePrompts';

interface StarMutationContext {
  previousPrompt?: Prompt;
  previousList?: PromptsResponse;
}

export function useStarPrompt() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: async ({ promptId }: { promptId: string }) => {
      const response = await fetch(`/api/prompts/${promptId}/star`, {
        method: 'POST',
      });
      if (!response.ok) throw new Error('Failed to star prompt');
      return response.json() as Promise<{ starred: boolean }>;
    },

    onMutate: async ({ promptId }): Promise<StarMutationContext> => {
      // Cancel outgoing queries
      await queryClient.cancelQueries({ queryKey: promptKeys.all });

      // Snapshot current state
      const previousPrompt = queryClient.getQueryData<Prompt>(
        promptKeys.detail(promptId)
      );

      // Optimistically update the detail
      if (previousPrompt) {
        queryClient.setQueryData<Prompt>(promptKeys.detail(promptId), {
          ...previousPrompt,
          isStarred: !previousPrompt.isStarred,
          starCount: previousPrompt.isStarred
            ? previousPrompt.starCount - 1
            : previousPrompt.starCount + 1,
        });
      }

      return { previousPrompt };
    },

    onError: (error, variables, context) => {
      // Rollback on error
      if (context?.previousPrompt) {
        queryClient.setQueryData(
          promptKeys.detail(variables.promptId),
          context.previousPrompt
        );
      }
    },

    onSettled: (data, error, variables) => {
      // Invalidate to refetch fresh data
      queryClient.invalidateQueries({
        queryKey: promptKeys.detail(variables.promptId),
      });
      queryClient.invalidateQueries({
        queryKey: promptKeys.lists(),
      });
    },
  });
}

// Create prompt mutation
export function useCreatePrompt() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: async (data: CreatePromptInput) => {
      const response = await fetch('/api/prompts', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(data),
      });
      if (!response.ok) {
        const error = await response.json();
        throw new Error(error.message || 'Failed to create prompt');
      }
      return response.json() as Promise<Prompt>;
    },

    onSuccess: (newPrompt) => {
      // Add to cache
      queryClient.setQueryData(
        promptKeys.detail(newPrompt.slug),
        newPrompt
      );

      // Invalidate lists to include new prompt
      queryClient.invalidateQueries({
        queryKey: promptKeys.lists(),
      });
    },
  });
}
```

## Prefetching Strategies

Implement smart prefetching:

```typescript
// lib/prefetch.ts
import { QueryClient } from '@tanstack/react-query';
import { promptKeys } from '@/hooks/queries/usePrompts';

export async function prefetchPrompt(queryClient: QueryClient, slug: string) {
  await queryClient.prefetchQuery({
    queryKey: promptKeys.detail(slug),
    queryFn: () => fetch(`/api/prompts/${slug}`).then((r) => r.json()),
    staleTime: 60 * 1000,
  });
}

// Component with prefetch on hover
export function PromptCard({ prompt }: { prompt: PromptSummary }) {
  const queryClient = useQueryClient();

  const handleMouseEnter = () => {
    // Prefetch prompt details on hover
    queryClient.prefetchQuery({
      queryKey: promptKeys.detail(prompt.slug),
      queryFn: () => fetch(`/api/prompts/${prompt.slug}`).then((r) => r.json()),
      staleTime: 60 * 1000,
    });
  };

  return (
    <Link
      href={`/prompts/${prompt.slug}`}
      onMouseEnter={handleMouseEnter}
      className="prompt-card"
    >
      <h3>{prompt.title}</h3>
      <p>{prompt.description}</p>
    </Link>
  );
}

// Server-side prefetching with Next.js
// app/prompts/[slug]/page.tsx
import { dehydrate, HydrationBoundary } from '@tanstack/react-query';
import { getQueryClient } from '@/lib/query-client';
import { promptKeys } from '@/hooks/queries/usePrompts';

export default async function PromptPage({ params }: { params: { slug: string } }) {
  const queryClient = getQueryClient();

  await queryClient.prefetchQuery({
    queryKey: promptKeys.detail(params.slug),
    queryFn: () => fetchPrompt(params.slug),
  });

  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <PromptDetail slug={params.slug} />
    </HydrationBoundary>
  );
}
```

## Query Composition

Combine queries for complex data needs:

```typescript
// hooks/queries/usePromptWithRelated.ts
import { useQueries, useQuery } from '@tanstack/react-query';

export function usePromptWithRelated(slug: string) {
  const promptQuery = useQuery({
    queryKey: promptKeys.detail(slug),
    queryFn: () => fetchPrompt(slug),
    enabled: Boolean(slug),
  });

  const relatedQueries = useQueries({
    queries: (promptQuery.data?.tags || []).slice(0, 3).map((tag) => ({
      queryKey: [...promptKeys.lists(), { tag, limit: 4 }],
      queryFn: () => fetchPrompts({ tag, limit: 4 }),
      enabled: Boolean(promptQuery.data),
    })),
  });

  const isLoading = promptQuery.isLoading || relatedQueries.some((q) => q.isLoading);
  const isError = promptQuery.isError || relatedQueries.some((q) => q.isError);

  const relatedPrompts = relatedQueries
    .flatMap((q) => q.data?.prompts || [])
    .filter((p) => p.slug !== slug)
    .slice(0, 6);

  return {
    prompt: promptQuery.data,
    relatedPrompts,
    isLoading,
    isError,
  };
}
```

## Best Practices

1. **Use query key factories** for consistent key management
2. **Implement optimistic updates** for better UX
3. **Configure appropriate stale times** based on data volatility
4. **Use suspense queries** with React Suspense boundaries
5. **Prefetch data** on hover for faster navigation
6. **Leverage infinite queries** for pagination
7. **Handle errors gracefully** with error boundaries