TanStack Query — Async State & Data Fetching for the Web

What it is

TanStack Query (formerly React Query) is an asynchronous state management library for TypeScript and JavaScript. It handles server-state caching, background updates, stale data revalidation, and data synchronization across React, Solid, Svelte, and Vue applications.

Frontend developers who fetch data from APIs and struggle with loading states, cache invalidation, and background refetching will find TanStack Query eliminates most of that boilerplate.

How it saves time or tokens

TanStack Query replaces custom useEffect + useState patterns for data fetching with a declarative API. It handles caching, deduplication, retries, and window focus refetching automatically. Developers write fewer lines of code and avoid common bugs like race conditions and stale closures.

How to use

1. Install @tanstack/react-query (or the adapter for your framework).
2. Wrap your app in a QueryClientProvider.
3. Use useQuery to fetch data and useMutation to modify it.

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

function UserProfile({ userId }: { userId: string }) {
  const { data, isLoading, error } = useQuery({
    queryKey: ['user', userId],
    queryFn: () => fetch(`/api/users/${userId}`).then(r => r.json()),
  });

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error loading user</div>;
  return <h1>{data.name}</h1>;
}

Example

Automatic cache invalidation after a mutation:

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

const queryClient = useQueryClient();
const mutation = useMutation({
  mutationFn: (newUser) => fetch('/api/users', {
    method: 'POST', body: JSON.stringify(newUser)
  }),
  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['users'] }),
});

Related on TokRepo

• AI coding tools — Tools and libraries for modern development
• Featured workflows — Discover popular developer tools and workflows

Common pitfalls

• Query keys must be serializable and unique. Inconsistent keys cause cache misses and duplicate requests.
• Over-fetching with too many queries on a single page can degrade performance. Use select to pick only needed fields.
• Stale time defaults to 0, meaning data is always considered stale. Adjust staleTime to reduce unnecessary refetches.