TanStack Query (React Query)

You've been fetching data wrong. I've seen production apps crash because developers treated server state like client state, caching blindly and invalidating never. TanStack Query (React Query) isn't just another data-fetching library—it's a paradigm shift that forces you to think in terms of stale-while-revalidate, background refetching, and optimistic updates. If you're still managing loading states with useState and useEffect, your codebase is already rotting. This is the blunt truth: without a dedicated server state manager, you're writing buggy, slow, and unmaintainable code. Let's fix that.

Why Server State Is Not Client State

Most developers treat API responses like local variables: fetch once, store in state, and forget. This works until the data changes on the server, the user navigates away and back, or another tab mutates the same resource. Server state is asynchronous, shared, and potentially stale. TanStack Query acknowledges this by design: it caches data but marks it as stale immediately, triggering background refetches when components remount or windows regain focus. This prevents the dreaded 'stale data' bug that plagues naive fetch-on-mount patterns. In production, I've seen apps display outdated inventory counts because they cached API responses indefinitely. With TanStack Query, you define a staleTime that matches your business requirements—for example, 30 seconds for a dashboard, 5 minutes for user profiles. The library handles the rest, including deduplication of concurrent requests and automatic garbage collection of unused caches.

import { useQuery } from '@tanstack/react-query';
import { getProducts } from './api';

export function useProducts() {
  return useQuery({
    queryKey: ['products'],
    queryFn: getProducts,
    staleTime: 30 * 1000, // 30 seconds
    gcTime: 5 * 60 * 1000, // 5 minutes (formerly cacheTime)
    refetchOnWindowFocus: true,
  });
}

Query Keys: The Foundation of Cache Management

Query keys are not just identifiers—they are the cache's address system. A poorly designed key leads to cache collisions, stale data, or unnecessary refetches. Keys can be strings or arrays of any serializable values. The rule: include all variables that affect the query result. For example, a paginated list should include the page number and filters in the key. If you omit a filter, changing it won't trigger a new fetch—you'll get the cached result from the previous filter. In production, I've debugged a bug where switching between user profiles showed the same data because the query key was just ['user']. The fix: ['user', userId]. TanStack Query also supports dependent queries: if a key includes a variable that is null, the query is disabled until that variable is defined. This eliminates the need for manual enabled checks.

import { useQuery } from '@tanstack/react-query';
import { getUser } from './api';

export function useUser(userId: string | undefined) {
  return useQuery({
    queryKey: ['user', userId],
    queryFn: () => getUser(userId!),
    enabled: !!userId, // query won't run if userId is undefined
  });
}

Mutations: The Other Half of the Equation

Fetching data is only half the story. Mutations (POST, PUT, DELETE) are where TanStack Query shines with optimistic updates and automatic cache invalidation. A mutation is a side effect that changes server state. After a mutation succeeds, you typically want to invalidate related queries so they refetch. But naive invalidation can cause a waterfall of requests. The better approach: use onMutate to optimistically update the cache, then onSettled to invalidate. This gives instant UI feedback while keeping the server as the source of truth. In production, I've seen apps that invalidate all queries on any mutation—this causes massive refetch storms. Instead, invalidate only the affected query keys. For example, after adding a new todo, invalidate ['todos'] but not ['users'].

import { useMutation, useQueryClient } from '@tanstack/react-query';
import { addTodo } from './api';

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

  return useMutation({
    mutationFn: addTodo,
    onMutate: async (newTodo) => {
      await queryClient.cancelQueries({ queryKey: ['todos'] });
      const previousTodos = queryClient.getQueryData(['todos']);
      queryClient.setQueryData(['todos'], (old: any) => [...old, newTodo]);
      return { previousTodos };
    },
    onError: (err, newTodo, context) => {
      queryClient.setQueryData(['todos'], context?.previousTodos);
    },
    onSettled: () => {
      queryClient.invalidateQueries({ queryKey: ['todos'] });
    },
  });
}

Background Refetching and Stale Time Tuning

TanStack Query's default behavior is to refetch on mount, window focus, and network reconnection. This is great for freshness but can be overkill. The staleTime option controls how long data is considered fresh. During the stale time, the cache is used without refetching. After stale time expires, data is still shown but a background refetch is triggered. Tuning staleTime is critical for performance. For example, a list of countries rarely changes—set staleTime to 24 hours. A stock ticker needs staleTime of 0. In production, we set staleTime to 5 minutes for user profiles, but 30 seconds for a dashboard. Also, use refetchInterval for polling: set it to 10 seconds for a live feed. But beware: polling can cause high server load. Combine with refetchIntervalInBackground to stop polling when the tab is hidden.

import { useQuery } from '@tanstack/react-query';
import { getStockPrice } from './api';

export function useStockPrice(symbol: string) {
  return useQuery({
    queryKey: ['stock', symbol],
    queryFn: () => getStockPrice(symbol),
    staleTime: 0, // always stale, refetch on mount/focus
    refetchInterval: 10_000, // poll every 10 seconds
    refetchIntervalInBackground: false, // stop polling when tab hidden
  });
}

Parallel and Dependent Queries

Real apps often need to fetch multiple resources in parallel or wait for one query to finish before starting another. TanStack Query handles both elegantly. For parallel queries, simply call useQuery multiple times—they will run concurrently. For dependent queries, use the enabled option to disable a query until its dependency is available. This is cleaner than chaining promises. In production, we had a user profile page that needed user data first, then their posts. We used enabled: !!user to defer the posts query until user was defined. This also automatically cancels the dependent query if the dependency changes. For truly sequential logic, you can use the result of one query as input to another, but be careful: if the dependency query fails, the dependent query won't run.

import { useQuery } from '@tanstack/react-query';
import { getUser, getPostsByUser } from './api';

export function useUserWithPosts(userId: string) {
  const userQuery = useQuery({
    queryKey: ['user', userId],
    queryFn: () => getUser(userId),
  });

  const postsQuery = useQuery({
    queryKey: ['posts', userId],
    queryFn: () => getPostsByUser(userId),
    enabled: !!userQuery.data, // wait until user is fetched
  });

  return { user: userQuery.data, posts: postsQuery.data, isLoading: userQuery.isLoading || postsQuery.isLoading };
}

Paginated and Infinite Queries

Handling pagination manually is error-prone. TanStack Query provides useQuery for offset-based pagination and useInfiniteQuery for cursor-based or infinite scroll. With useQuery, you include the page number in the query key and use keepPreviousData to show the previous page's data while fetching the next. This prevents layout shifts. For infinite queries, useInfiniteQuery manages page parameters and provides fetchNextPage and hasNextPage. In production, we used useInfiniteQuery for a feed with cursor-based pagination. The key insight: set staleTime to a reasonable value so that revisiting a page doesn't refetch from scratch. Also, use getNextPageParam to extract the cursor from the response. If the API returns a nextCursor, return it; otherwise return undefined to signal end of list.

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

export function useInfiniteFeed() {
  return useInfiniteQuery({
    queryKey: ['feed'],
    queryFn: ({ pageParam = 0 }) => getFeed({ cursor: pageParam }),
    initialPageParam: 0,
    getNextPageParam: (lastPage) => lastPage.nextCursor ?? undefined,
    staleTime: 60_000,
  });
}

Cache Invalidation Strategies

Invalidation is how you tell TanStack Query that cached data is no longer valid. The simplest way is queryClient.invalidateQueries({ queryKey: ['todos'] }). This marks the query as stale and triggers a refetch if the query is currently active. But aggressive invalidation can cause unnecessary refetches. A better strategy: invalidate only when a mutation succeeds, and use exact matching or predicate functions to target specific queries. For example, after updating a todo, invalidate only ['todos', todoId] instead of all todos. Also, consider using refetchType: 'active' to only refetch queries that are currently being used. In production, we had a dashboard with multiple widgets; invalidating all queries on any mutation caused a spike in API calls. We switched to targeted invalidation and saw a 50% reduction in requests.

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

const queryClient = useQueryClient();

// Invalidate all todo queries
queryClient.invalidateQueries({ queryKey: ['todos'] });

// Invalidate only a specific todo
queryClient.invalidateQueries({ queryKey: ['todos', todoId] });

// Invalidate with predicate (e.g., all queries that start with 'todos')
queryClient.invalidateQueries({
  predicate: (query) => query.queryKey[0] === 'todos',
});

// Refetch only active queries
queryClient.invalidateQueries({ queryKey: ['todos'], refetchType: 'active' });

Error Handling and Retry Logic

Network requests fail. TanStack Query provides built-in retry logic with exponential backoff. By default, it retries 3 times with a delay that doubles each time. You can customize retry count, delay, and conditions. For example, don't retry on 4xx errors (client errors) because they are unlikely to succeed. Use retry: (failureCount, error) => error.status !== 404 to skip retries for not found. Also, use onError callback to show toast notifications or log errors. In production, we had a mutation that failed with a 409 conflict; retrying would never succeed, so we set retry: false for that mutation. For queries, we set retryDelay to a fixed 1 second for time-sensitive data. Remember: retries happen in the background; the UI still shows the previous data until a successful fetch.

import { useQuery } from '@tanstack/react-query';
import { getUser } from './api';

export function useUserWithRetry(userId: string) {
  return useQuery({
    queryKey: ['user', userId],
    queryFn: () => getUser(userId),
    retry: (failureCount, error: any) => {
      if (error.status === 404) return false; // don't retry on 404
      return failureCount < 3;
    },
    retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 10000), // exponential backoff capped at 10s
  });
}

Devtools: Debugging Cache State

TanStack Query Devtools are a browser extension that shows the cache state, query status, and allows manual invalidation. It's invaluable for debugging. You can see which queries are stale, fetching, or inactive. You can also trigger refetches or remove queries from the cache. In production, we use it to verify that cache invalidation works correctly. The devtools are only included in development builds by default. To enable them, add <ReactQueryDevtools /> to your app. They are tree-shaken in production. One tip: use the devtools to inspect query keys and ensure they match your expectations. I've caught many bugs where a query key was missing a parameter, causing cache collisions.

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';

const queryClient = new QueryClient();

export function App() {
  return (
    <QueryClientProvider client={queryClient}>
      {/* Your app */}
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  );
}

Performance Optimization: Selectors and Structural Sharing

TanStack Query re-renders components only when the selected data changes. Use the select option to transform or pick a subset of data. This prevents unnecessary re-renders when other parts of the cache update. For example, if you only need a user's name, select: (user) => user.name. The component will only re-render when the name changes, not when other user fields update. Additionally, TanStack Query uses structural sharing by default: it compares the previous and new data deeply and returns the same reference if nothing changed. This is a huge performance win for immutable data. In production, we had a component that rendered a list of items; without select, it re-rendered on every background refetch even if the list was identical. Adding select to pick only the needed fields reduced re-renders by 90%.

import { useQuery } from '@tanstack/react-query';
import { getUser } from './api';

export function useUserName(userId: string) {
  return useQuery({
    queryKey: ['user', userId],
    queryFn: () => getUser(userId),
    select: (user) => user.name, // only subscribe to name changes
  });
}

Testing Queries and Mutations

Testing TanStack Query code requires mocking the query client and network. Use @tanstack/react-query's QueryClientProvider with a fresh QueryClient in tests. For network mocking, use MSW (Mock Service Worker) or simple jest mocks. The key is to wrap your component in a test QueryClientProvider and use waitFor to assert on loading and success states. For mutations, use renderHook with useMutation and assert on mutateAsync. In production, we write integration tests that verify cache invalidation: after a mutation, the related query should refetch. We also test error states by making the mock reject. One common pitfall: forgetting to reset the query client between tests, causing cached data to leak. Always create a new QueryClient for each test.

import { renderHook, waitFor } from '@testing-library/react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { useProducts } from './useProducts';

const createWrapper = () => {
  const queryClient = new QueryClient({
    defaultOptions: { queries: { retry: false } }, // disable retries for tests
  });
  return ({ children }: { children: React.ReactNode }) => (
    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
  );
};

it('fetches products', async () => {
  const { result } = renderHook(() => useProducts(), { wrapper: createWrapper() });

  expect(result.current.isLoading).toBe(true);

  await waitFor(() => expect(result.current.isSuccess).toBe(true));

  expect(result.current.data).toEqual([{ id: 1, name: 'Product A' }]);
});

TanStack Query v5 Breaking Changes

TanStack Query v5 introduces several breaking changes that require attention when upgrading from v4. Key changes include:

1. Removal of keepPreviousData: Replaced by placeholderData with keepPreviousData function.
2. Query Key Structure: Query keys must be arrays; string-only keys are no longer supported.
3. onSuccess, onError, onSettled Deprecated: These callbacks are removed from useQuery and useMutation. Use queryClient's event handlers or side effects in components.
4. useMutation Return Value: mutate no longer returns a promise; use mutateAsync for promise-based usage.
5. cacheTime Renamed to gcTime: The option cacheTime is now gcTime (garbage collection time).
6. useQueries Syntax: The queries option now requires an array of query objects directly, not a function returning an array.
7. TypeScript Improvements: Better type inference for query keys and data.

To migrate, update all query keys to arrays, replace keepPreviousData with placeholderData: keepPreviousData, and move side effects from callbacks to useEffect or queryClient observers. For mutations, switch to mutateAsync if you need promises. Rename cacheTime to gcTime. Review the official migration guide for a complete list.

// v4
const query = useQuery('todos', fetchTodos, {
  keepPreviousData: true,
  onSuccess: (data) => console.log(data),
})

// v5
const query = useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
  placeholderData: keepPreviousData,
})

// v4 mutation
const mutation = useMutation(updateTodo, {
  onSuccess: () => queryClient.invalidateQueries('todos'),
})
mutation.mutate(newTodo)

// v5 mutation
const mutation = useMutation({
  mutationFn: updateTodo,
  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
})
mutation.mutateAsync(newTodo).then(() => console.log('done'))

useSuspenseQuery for Suspense-first Data Fetching

useSuspenseQuery is a new hook in TanStack Query v5 that integrates with React's Suspense for a more declarative data fetching pattern. Unlike useQuery, which returns loading states, useSuspenseQuery throws a promise during data fetching, allowing Suspense boundaries to handle loading states automatically.

Usage: Wrap your component in a <Suspense> boundary. Inside, use useSuspenseQuery with the same options as useQuery (except enabled and placeholderData are not supported). The hook returns data directly (no isLoading).

Example: ```tsx function TodoList() { const { data } = useSuspenseQuery({ queryKey: ['todos'], queryFn: fetchTodos, }) return <ul>{data.map(todo => <li key={todo.id}>{todo.title}</li>)}</ul> }

function App() { return ( <Suspense fallback={<div>Loading...</div>}> <TodoList /> </Suspense> ) } ```

Error Handling: Use an ErrorBoundary to catch errors thrown by useSuspenseQuery. Alternatively, use useSuspenseQuery's throwOnError option.

import { useSuspenseQuery } from '@tanstack/react-query'
import { Suspense, ErrorBoundary } from 'react'

function UserProfile({ userId }: { userId: string }) {
  const { data } = useSuspenseQuery({
    queryKey: ['user', userId],
    queryFn: () => fetchUser(userId),
  })
  return <div>{data.name}</div>
}

export default function App() {
  return (
    <ErrorBoundary fallback={<div>Error loading user</div>}>
      <Suspense fallback={<div>Loading user...</div>}>
        <UserProfile userId="1" />
      </Suspense>
    </ErrorBoundary>
  )
}

Query Key Factory Pattern

The Query Key Factory pattern provides a type-safe and maintainable way to manage query keys in TanStack Query. Instead of scattering string literals across your codebase, you define a factory object that generates query keys with proper typing.

Implementation: Create a factory object with methods that return query keys as arrays. Use as const or satisfy QueryKey type for strictness.

Example: ```tsx // queryKeyFactory.ts import { createQueryKeyStore } from '@lukemorales/query-key-factory'

// Or manual factory: export const todoKeys = { all: ['todos'] as const, lists: () => [...todoKeys.all, 'list'] as const, list: (filters: { status?: string }) => [...todoKeys.lists(), filters] as const, details: () => [...todoKeys.all, 'detail'] as const, detail: (id: number) => [...todoKeys.details(), id] as const, }

// Usage in hooks: function useTodos(filters: { status?: string }) { return useQuery({ queryKey: todoKeys.list(filters), queryFn: () => fetchTodos(filters), }) }

function useTodo(id: number) { return useQuery({ queryKey: todoKeys.detail(id), queryFn: () => fetchTodo(id), }) }

// Invalidation: queryClient.invalidateQueries({ queryKey: todoKeys.all }) queryClient.invalidateQueries({ queryKey: todoKeys.lists() }) ```

Library Support: The @lukemorales/query-key-factory library provides a createQueryKeyStore helper for even more concise factories.

import { createQueryKeyStore } from '@lukemorales/query-key-factory'

export const todoKeys = createQueryKeyStore({
  todos: {
    all: null,
    list: (filters: { status?: string }) => [filters],
    detail: (id: number) => [id],
  },
})

// Usage
const { data } = useQuery({
  queryKey: todoKeys.todos.list({ status: 'done' }),
  queryFn: () => fetchTodos({ status: 'done' }),
})

queryClient.invalidateQueries({ queryKey: todoKeys.todos.all })