TanStack

# TanStack

## Overview

The TanStack ecosystem provides type-safe client libraries for React: Query for declarative data fetching and caching, Router for fully typed routing with search parameters, Table for headless data tables with sorting/filtering/pagination, and Virtual for rendering large lists efficiently.

## Instructions

- When fetching data, use `useQuery()` with hierarchical query keys (e.g., `["users", userId, "posts"]`) and configure `staleTime` based on freshness needs (0 for real-time, 5 minutes for dashboards, Infinity for static data).
- When performing mutations, use `useMutation()` with `onSuccess` for cache invalidation via `queryClient.invalidateQueries()`, and `onMutate` for optimistic updates with rollback.
- When building tables, use TanStack Table's headless approach with typed column definitions, and combine with `@tanstack/react-virtual` for datasets with 10,000+ rows.
- When routing, use TanStack Router for fully typed route parameters and search params with Zod validation, file-based routes with automatic type generation, and route-level data loading.
- When handling pagination, use `useInfiniteQuery()` for infinite scroll or cursor-based patterns, and server-side pagination in TanStack Table.
- When prefetching, use `queryClient.prefetchQuery()` for anticipated navigation and `useSuspenseQuery()` for React Suspense integration.
- When virtualizing lists, use `@tanstack/react-virtual` with `estimateSize` for scroll position prediction and support for dynamic, variable-height items.

## Examples

### Example 1: Build a data dashboard with Query and Table

**User request:** "Create a dashboard with server-paginated data table and real-time stats"

**Actions:**
1. Set up TanStack Query with appropriate `staleTime` and refetch intervals for stats
2. Define TanStack Table with typed columns, server-side sorting and pagination
3. Implement filter controls with column filters and global search
4. Add optimistic updates for inline row editing with mutation rollback

**Output:** A dashboard with efficient data fetching, server-managed table pagination, and instant edit feedback.

### Example 2: Add type-safe routing with data prefetching

**User request:** "Set up TanStack Router with typed search parameters and data preloading"

**Actions:**
1. Define routes with typed parameters and Zod-validated search params
2. Add route loaders for data fetching with built-in caching
3. Configure `<Link>` components with type-checked params and search params
4. Enable prefetching on hover for instant navigation

**Output:** A fully typed routing layer where invalid params cause TypeScript errors at compile time.

## Guidelines

- Use query key factories for consistent cache keys: `const userKeys = { all: ["users"], detail: (id) => ["users", id] }`.
- Set `staleTime` based on data freshness needs: 0 for real-time, 5 minutes for dashboards, Infinity for static data.
- Always define `onError` for mutations; silent failures confuse users.
- Use `placeholderData` instead of `initialData` for loading states; placeholder does not write to cache.
- Use TanStack Table with `@tanstack/react-virtual` for large datasets; do not render thousands of DOM nodes.
- Keep query functions pure: they receive `queryKey` and return data with no side effects.
- Use `queryClient.invalidateQueries()` after mutations instead of manual cache updates for simplicity.