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.