Tanstack Query

API Client (ky)

// lib/api/client.ts
import ky from 'ky';
import { useAuthStore } from '@/stores/auth';

export const api = ky.create({
  prefixUrl: import.meta.env.PUBLIC_API_URL,
  timeout: 30000,
  hooks: {
    beforeRequest: [
      (request) => {
        const token = useAuthStore.getState().token;
        if (token) request.headers.set('Authorization', `Bearer ${token}`);
      },
    ],
    afterResponse: [
      async (_, __, response) => {
        if (response.status === 401) {
          useAuthStore.getState().logout();
          window.location.href = '/login';
        }
        return response;
      },
    ],
  },
});

Query Keys Factory

// lib/query/keys.ts
export const queryKeys = {
  items: {
    all: ['items'] as const,
    lists: () => [...queryKeys.items.all, 'list'] as const,
    list: (filters: ItemFilters) => [...queryKeys.items.lists(), filters] as const,
    details: () => [...queryKeys.items.all, 'detail'] as const,
    detail: (id: string) => [...queryKeys.items.details(), id] as const,
  },
  users: {
    all: ['users'] as const,
    current: () => [...queryKeys.users.all, 'current'] as const,
    detail: (id: string) => [...queryKeys.users.all, 'detail', id] as const,
  },
} as const;

Query Hooks

// Basic query
export function useItems(filters: ItemFilters = {}) {
  return useQuery({
    queryKey: queryKeys.items.list(filters),
    queryFn: async () => {
      const response = await api.get('items', { searchParams: filters }).json();
      return ItemsResponseSchema.parse(response);
    },
  });
}

// Query with ID
export function useItem(id: string) {
  return useQuery({
    queryKey: queryKeys.items.detail(id),
    queryFn: async () => {
      const response = await api.get(`items/${id}`).json();
      return ItemSchema.parse(response.data);
    },
    enabled: !!id,  // Only run if id exists
  });
}

// Dependent query
export function useItemDetails(itemId: string) {
  const { data: item } = useItem(itemId);

  return useQuery({
    queryKey: [...queryKeys.items.detail(itemId), 'details'],
    queryFn: () => api.get(`items/${itemId}/details`).json(),
    enabled: !!item,  // Only run after item is loaded
    staleTime: 1000 * 30,  // 30 seconds for real-time data
  });
}

Infinite Query (Pagination)

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

export function useItemsInfinite(filters: ItemFilters = {}) {
  return useInfiniteQuery({
    queryKey: queryKeys.items.list(filters),
    queryFn: async ({ pageParam = 1 }) => {
      const response = await api.get('items', {
        searchParams: { ...filters, page: pageParam, limit: 20 },
      }).json();
      return ItemsResponseSchema.parse(response);
    },
    initialPageParam: 1,
    getNextPageParam: (lastPage) => {
      const { page, limit, total } = lastPage.meta;
      return page * limit < total ? page + 1 : undefined;
    },
  });
}

// Usage
function ItemList() {
  const { data, fetchNextPage, hasNextPage, isFetchingNextPage } = useItemsInfinite();
  const items = data?.pages.flatMap(page => page.data) ?? [];

  return (
    <div>
      {items.map(item => <ItemCard key={item.id} item={item} />)}
      {hasNextPage && (
        <Button onClick={() => fetchNextPage()} loading={isFetchingNextPage}>
          Load More
        </Button>
      )}
    </div>
  );
}

Mutations

// Basic mutation
export function useCreateItem() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: async (input: CreateItemInput) => {
      const response = await api.post('items', { json: input }).json();
      return ItemSchema.parse(response.data);
    },
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: queryKeys.items.lists() });
    },
  });
}

// Optimistic update mutation
export function useUpdateItem() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: async ({ id, ...input }: UpdateItemInput & { id: string }) => {
      const response = await api.put(`items/${id}`, { json: input }).json();
      return ItemSchema.parse(response.data);
    },
    onMutate: async ({ id, ...input }) => {
      await queryClient.cancelQueries({ queryKey: queryKeys.items.detail(id) });

      const previousItem = queryClient.getQueryData<Item>(queryKeys.items.detail(id));

      if (previousItem) {
        queryClient.setQueryData(queryKeys.items.detail(id), { ...previousItem, ...input });
      }

      return { previousItem };
    },
    onError: (err, { id }, context) => {
      if (context?.previousItem) {
        queryClient.setQueryData(queryKeys.items.detail(id), context.previousItem);
      }
    },
    onSettled: (_, __, { id }) => {
      queryClient.invalidateQueries({ queryKey: queryKeys.items.detail(id) });
      queryClient.invalidateQueries({ queryKey: queryKeys.items.lists() });
    },
  });
}

// Delete with optimistic update
export function useDeleteItem() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: (id: string) => api.delete(`items/${id}`),
    onMutate: async (id) => {
      await queryClient.cancelQueries({ queryKey: queryKeys.items.lists() });

      const previousData = queryClient.getQueriesData({ queryKey: queryKeys.items.lists() });

      queryClient.setQueriesData({ queryKey: queryKeys.items.lists() }, (old: any) => {
        if (!old) return old;
        return { ...old, data: old.data.filter((item: Item) => item.id !== id) };
      });

      return { previousData };
    },
    onError: (_, __, context) => {
      context?.previousData.forEach(([key, data]) => {
        queryClient.setQueryData(key, data);
      });
    },
    onSettled: () => {
      queryClient.invalidateQueries({ queryKey: queryKeys.items.lists() });
    },
  });
}

Prefetching

// Prefetch on hover
function ItemRow({ item }: { item: Item }) {
  const queryClient = useQueryClient();

  const prefetch = () => {
    queryClient.prefetchQuery({
      queryKey: queryKeys.items.detail(item.id),
      queryFn: () => api.get(`items/${item.id}`).json(),
      staleTime: 1000 * 60,
    });
  };

  return (
    <Link to={`/items/${item.id}`} onMouseEnter={prefetch} onFocus={prefetch}>
      {item.name}
    </Link>
  );
}

// Route loader prefetch
export async function itemLoader({ params }: { params: { id: string } }) {
  await queryClient.ensureQueryData({
    queryKey: queryKeys.items.detail(params.id),
    queryFn: () => api.get(`items/${params.id}`).json(),
  });
  return null;
}

Polling

// Auto-refresh every 5 seconds
export function useItemRealtime(id: string) {
  return useQuery({
    queryKey: queryKeys.items.detail(id),
    queryFn: () => api.get(`items/${id}`).json(),
    refetchInterval: 5000,
    refetchIntervalInBackground: false,  // Pause when tab inactive
  });
}

// Conditional polling
export function useAlertsPolling(enabled: boolean) {
  return useQuery({
    queryKey: ['alerts', 'unread'],
    queryFn: () => api.get('alerts/unread').json(),
    refetchInterval: enabled ? 10000 : false,
  });
}

Suspense

import { useSuspenseQuery } from '@tanstack/react-query';

function ItemDetail({ id }: { id: string }) {
  // Data is guaranteed to exist (no undefined check needed)
  const { data: item } = useSuspenseQuery({
    queryKey: queryKeys.items.detail(id),
    queryFn: () => api.get(`items/${id}`).json(),
  });

  return <div>{item.name}</div>;
}

// Parent with Suspense boundary
function ItemPage({ id }: { id: string }) {
  return (
    <Suspense fallback={<LoadingSpinner />}>
      <ItemDetail id={id} />
    </Suspense>
  );
}

Parallel Queries

import { useQueries } from '@tanstack/react-query';

export function useDashboardData(id: string) {
  return useQueries({
    queries: [
      {
        queryKey: queryKeys.items.list({ parentId: id }),
        queryFn: () => api.get('items', { searchParams: { parentId: id } }).json(),
      },
      {
        queryKey: ['alerts', { parentId: id }],
        queryFn: () => api.get('alerts', { searchParams: { parentId: id } }).json(),
      },
      {
        queryKey: ['stats', id],
        queryFn: () => api.get(`stats/${id}`).json(),
      },
    ],
    combine: (results) => ({
      items: results[0].data?.data ?? [],
      alerts: results[1].data?.data ?? [],
      stats: results[2].data?.data ?? null,
      isLoading: results.some(r => r.isLoading),
      isError: results.some(r => r.isError),
    }),
  });
}

Select & Transform

// Transform data in hook
export function useItemNames() {
  return useQuery({
    queryKey: queryKeys.items.lists(),
    queryFn: () => api.get('items').json(),
    select: (data) => data.data.map(item => ({ id: item.id, name: item.name })),
  });
}

// Filter with select
export function useActiveItems() {
  return useQuery({
    queryKey: queryKeys.items.lists(),
    queryFn: () => api.get('items').json(),
    select: (data) => data.data.filter(item => item.status === 'active'),
  });
}

Error Handling

// Global error handler
import { QueryCache, MutationCache } from '@tanstack/react-query';

export const queryClient = new QueryClient({
  queryCache: new QueryCache({
    onError: (error, query) => {
      if (query.meta?.errorBoundary) return;
      notify.error(`Error: ${error.message}`);
    },
  }),
  mutationCache: new MutationCache({
    onError: (error) => notify.error(`Error: ${error.message}`),
  }),
});

Best Practices

1. Always use queryKeys factory: queryKeys.items.detail(id) not ['items', id]
2. Validate responses with Zod: return Schema.parse(response)
3. Configure staleTime: 5min for slow-changing, 10sec for real-time data
4. Use enabled for conditional queries: enabled: !!userId && isActive
5. Invalidate related queries: Update lists when detail changes

Related Skills

• frontend-web: Full frontend integration
• mantine-ui: UI components with queries
• zod-validation: Response validation
• fastapi: Backend API patterns