React Query Data Fetching Patterns

# React Query Data Fetching Patterns

Build efficient data fetching layers with TanStack Query (React Query) in your Google Antigravity applications. This guide covers queries, mutations, caching strategies, and optimistic updates.

## Query Client Setup

Configure TanStack Query with sensible 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: 10 * 60 * 1000, // 10 minutes
        retry: (failureCount, error) => {
          if (error instanceof Response && error.status === 404) {
            return false;
          }
          return failureCount < 3;
        },
        refetchOnWindowFocus: false,
      },
      mutations: {
        retry: 1,
      },
    },
  });
}

// app/providers.tsx
"use client";

import { QueryClientProvider } from "@tanstack/react-query";
import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
import { useState } from "react";
import { makeQueryClient } from "@/lib/query-client";

export function Providers({ children }: { children: React.ReactNode }) {
  const [queryClient] = useState(() => makeQueryClient());

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

## Query Hooks

Create reusable query hooks:

```typescript
// hooks/usePrompts.ts
import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
import { createClient } from "@/lib/supabase/client";

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: (id: string) => [...promptKeys.details(), id] as const,
};

export function usePrompts(filters: PromptFilters = {}) {
  return useQuery({
    queryKey: promptKeys.list(filters),
    queryFn: async () => {
      const supabase = createClient();
      let query = supabase
        .from("prompts")
        .select("*")
        .eq("is_approved", true)
        .order("created_at", { ascending: false });

      if (filters.category) {
        query = query.contains("tags", [filters.category]);
      }

      const { data, error } = await query;
      if (error) throw error;
      return data;
    },
  });
}

export function usePrompt(id: string) {
  return useQuery({
    queryKey: promptKeys.detail(id),
    queryFn: async () => {
      const supabase = createClient();
      const { data, error } = await supabase
        .from("prompts")
        .select("*")
        .eq("id", id)
        .single();

      if (error) throw error;
      return data;
    },
    enabled: !!id,
  });
}
```

## Mutations with Optimistic Updates

Implement optimistic updates for instant feedback:

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

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

  return useMutation({
    mutationFn: async ({ promptId, userId }: { promptId: string; userId: string }) => {
      const supabase = createClient();
      const { error } = await supabase
        .from("stars")
        .insert({ prompt_id: promptId, user_id: userId });
      if (error) throw error;
    },
    onMutate: async ({ promptId }) => {
      await queryClient.cancelQueries({ queryKey: promptKeys.detail(promptId) });
      const previousPrompt = queryClient.getQueryData<Prompt>(
        promptKeys.detail(promptId)
      );
      if (previousPrompt) {
        queryClient.setQueryData(promptKeys.detail(promptId), {
          ...previousPrompt,
          star_count: previousPrompt.star_count + 1,
          is_starred: true,
        });
      }
      return { previousPrompt };
    },
    onError: (err, { promptId }, context) => {
      if (context?.previousPrompt) {
        queryClient.setQueryData(
          promptKeys.detail(promptId),
          context.previousPrompt
        );
      }
    },
    onSettled: (_, __, { promptId }) => {
      queryClient.invalidateQueries({ queryKey: promptKeys.detail(promptId) });
    },
  });
}
```

## Infinite Queries

Implement infinite scrolling:

```typescript
// hooks/useInfinitePrompts.ts
import { useInfiniteQuery } from "@tanstack/react-query";

export function useInfinitePrompts() {
  return useInfiniteQuery({
    queryKey: ["prompts", "infinite"],
    queryFn: async ({ pageParam = 0 }) => {
      const supabase = createClient();
      const limit = 20;
      const from = pageParam * limit;
      const to = from + limit - 1;

      const { data, error, count } = await supabase
        .from("prompts")
        .select("*", { count: "exact" })
        .eq("is_approved", true)
        .order("created_at", { ascending: false })
        .range(from, to);

      if (error) throw error;
      return { data, nextPage: to < (count || 0) - 1 ? pageParam + 1 : undefined };
    },
    getNextPageParam: (lastPage) => lastPage.nextPage,
    initialPageParam: 0,
  });
}
```

## Best Practices

1. **Query Keys**: Use structured query key factories for consistency
2. **Stale Time**: Set appropriate stale times based on data freshness needs
3. **Optimistic Updates**: Provide instant feedback for better UX
4. **Error Handling**: Implement proper error boundaries and retry logic
5. **Prefetching**: Prefetch data on hover for perceived performance
6. **Devtools**: Use React Query Devtools during development