## The Problem React Doesn't Solve React is extraordinarily good at one thing: **rendering UI as a function of state**. Give it state, it gives you a screen. Change the state, the screen updates. Clean, predictable, composable. What React does *not* give you is any opinion on where that state comes from. For local, ephemeral UI state — whether a modal is open, which tab is selected, what the user typed in a field — `useState` and `useReducer` are perfect. But the moment you need to fetch data from a server, the situation gets complicated fast. Consider what a "simple" data-fetching pattern in vanilla React actually requires: ```tsx function UserProfile({ userId }: { userId: string }) { const [user, setUser] = useState(null); const [isLoading, setIsLoading] = useState(true); const [error, setError] = useState(null); useEffect(() => { let cancelled = false; setIsLoading(true); fetch(`/api/users/${userId}`) .then((res) => res.json()) .then((data) => { if (!cancelled) { setUser(data); setIsLoading(false); } }) .catch((err) => { if (!cancelled) { setError(err); setIsLoading(false); } }); return () => { cancelled = true; }; }, [userId]); if (isLoading) return ; if (error) return ; return ; } ``` And this is still the *happy path*. We haven't handled: - **Caching**: if the user navigates away and back, do we fetch again? - **Deduplication**: if two components mount simultaneously and both need this user, do we send two requests? - **Background refetching**: if the data might have changed, when do we refresh? - **Stale data**: should we show the old data while fetching the new? - **Retry logic**: if the request fails, should we try again? - **Pagination**: how do we load more items without blowing up memory? - **Optimistic updates**: how do we reflect a mutation immediately before the server confirms it? This is **server state management** — and it's a fundamentally different problem from UI state management. React Query (officially known as **TanStack Query**) exists to solve exactly this. ## What Is React Query? React Query is an asynchronous state management library for React (with adapters for Vue, Solid, Svelte, and Angular via TanStack Query). It provides a set of hooks and utilities that handle the full lifecycle of server-side data in your application. At its core, React Query introduces two primitives: - **Queries** — for reading data from a server (GET) - **Mutations** — for writing data to a server (POST, PUT, PATCH, DELETE) But the real value isn't in those primitives themselves. It's in everything React Query *automatically manages* around them: a **smart, normalized cache** with configurable staleness, background synchronization, request deduplication, retry strategies, garbage collection, and developer tooling. Installed by more than **10 million projects per week** on npm, React Query has become the de facto standard for server state in React applications. ## Getting Started ### Installation ```bash npm install @tanstack/react-query # Optional but highly recommended npm install @tanstack/react-query-devtools ``` ### Provider Setup Wrap your application with a `QueryClientProvider`: ```tsx // app/layout.tsx (Next.js App Router) import { QueryClient, QueryClientProvider } from '@tanstack/react-query'; import { ReactQueryDevtools } from '@tanstack/react-query-devtools'; const queryClient = new QueryClient(); export default function RootLayout({ children }: { children: React.ReactNode }) { return ( {children} ); } ``` > **Note for Next.js App Router users**: since `QueryClientProvider` is a client component, you'll want to extract it into a `'use client'` wrapper component. The TanStack Query docs cover this pattern in detail. ## The `useQuery` Hook The `useQuery` hook is your primary tool for fetching and caching data. Let's rewrite the earlier example: ```tsx import { useQuery } from '@tanstack/react-query'; async function fetchUser(userId: string): Promise { const res = await fetch(`/api/users/${userId}`); if (!res.ok) throw new Error('Failed to fetch user'); return res.json(); } function UserProfile({ userId }: { userId: string }) { const { data: user, isLoading, isError, error } = useQuery({ queryKey: ['user', userId], queryFn: () => fetchUser(userId), }); if (isLoading) return ; if (isError) return ; return ; } ``` Same behavior, a fraction of the code. But more importantly: **you're now getting all the features you weren't handling before** — caching, deduplication, background refetching — for free. ### The `queryKey` The `queryKey` is the most important concept in React Query. It's an array that uniquely identifies a query. React Query uses it to: - **Store and retrieve** results from the cache - **Deduplicate** concurrent requests with the same key - **Invalidate** specific slices of data after mutations Keys are hierarchical and serializable: ```tsx // A list of all users useQuery({ queryKey: ['users'], queryFn: fetchUsers }); // A specific user useQuery({ queryKey: ['user', userId], queryFn: () => fetchUser(userId) }); // A user's posts, filtered useQuery({ queryKey: ['user', userId, 'posts', { status: 'published' }], queryFn: () => fetchUserPosts(userId, 'published'), }); ``` When you invalidate `['user', userId]`, React Query also invalidates everything nested under that key — including `['user', userId, 'posts', ...]`. This makes cache management feel intuitive rather than brittle. ### `queryFn`: Bring Your Own Fetcher React Query is agnostic about *how* you fetch. The `queryFn` can use `fetch`, `axios`, `ky`, a GraphQL client, or any async function that returns data or throws an error: ```tsx // With axios queryFn: () => axios.get(`/api/users/${userId}`).then(r => r.data) // With a GraphQL client queryFn: () => graphqlClient.request(USER_QUERY, { userId }) // With tRPC queryFn: () => trpc.user.byId.query({ userId }) ``` ## Key Features Deep Dive ### Caching and Stale-While-Revalidate React Query implements the **stale-while-revalidate** (SWR) pattern. When you navigate back to a screen whose data is already cached, React Query: 1. **Immediately returns the cached data** (so the UI renders instantly) 2. **Fetches fresh data in the background** 3. **Updates the UI** if the fresh data differs You control how long data is considered "fresh" with `staleTime`: ```tsx useQuery({ queryKey: ['user', userId], queryFn: () => fetchUser(userId), staleTime: 1000 * 60 * 5, // data is fresh for 5 minutes }); ``` With `staleTime: Infinity`, data is never automatically refetched — useful for static reference data like country lists or configuration. ### Automatic Retries Failed requests are automatically retried 3 times (with exponential backoff) before the query enters the `error` state. Fully configurable: ```tsx useQuery({ queryKey: ['user', userId], queryFn: () => fetchUser(userId), retry: 2, retryDelay: (attempt) => Math.min(1000 * 2 ** attempt, 30000), }); ``` ### Window Focus Refetching When a user tabs away and comes back, React Query refetches stale queries automatically. This means your users almost never see stale data without you writing a single line of polling logic. Disable it per-query or globally if needed: ```tsx useQuery({ queryKey: ['user', userId], queryFn: () => fetchUser(userId), refetchOnWindowFocus: false, }); ``` ### Request Deduplication If two components mount at the same time and both call `useQuery` with the same key, **React Query sends exactly one request** and shares the result with both. This is automatic and requires no coordination on your part. ## Mutations with `useMutation` Reading data is only half the story. The `useMutation` hook handles write operations: ```tsx import { useMutation, useQueryClient } from '@tanstack/react-query'; function UpdateUsernameForm({ userId }: { userId: string }) { const queryClient = useQueryClient(); const mutation = useMutation({ mutationFn: (newUsername: string) => fetch(`/api/users/${userId}`, { method: 'PATCH', body: JSON.stringify({ username: newUsername }), }).then((r) => r.json()), onSuccess: () => { // Invalidate the cache so the updated user is refetched queryClient.invalidateQueries({ queryKey: ['user', userId] }); }, }); return ( ); } ``` After a successful mutation, `invalidateQueries` marks the relevant cache entries as stale, triggering a background refetch. The UI stays consistent without manual state updates. ### Optimistic Updates For a snappier UX, you can update the cache *before* the server responds and roll back if the request fails: ```tsx const mutation = useMutation({ mutationFn: updateUsername, onMutate: async (newUsername) => { // Cancel any in-flight refetches await queryClient.cancelQueries({ queryKey: ['user', userId] }); // Snapshot the current value const previousUser = queryClient.getQueryData(['user', userId]); // Optimistically update the cache queryClient.setQueryData(['user', userId], (old: User) => ({ ...old, username: newUsername, })); // Return the snapshot for rollback return { previousUser }; }, onError: (err, newUsername, context) => { // Roll back on error queryClient.setQueryData(['user', userId], context?.previousUser); }, onSettled: () => { queryClient.invalidateQueries({ queryKey: ['user', userId] }); }, }); ``` The result: the UI updates instantly, and if the server rejects the change, it snaps back transparently. ## Pagination and Infinite Queries React Query ships first-class support for paginated and infinite-scroll data via `useInfiniteQuery`: ```tsx import { useInfiniteQuery } from '@tanstack/react-query'; function PostFeed() { const { data, fetchNextPage, hasNextPage, isFetchingNextPage, } = useInfiniteQuery({ queryKey: ['posts'], queryFn: ({ pageParam = 1 }) => fetchPosts({ page: pageParam }), getNextPageParam: (lastPage) => lastPage.nextPage ?? undefined, initialPageParam: 1, }); const posts = data?.pages.flatMap((page) => page.items) ?? []; return ( <> {posts.map((post) => )} ); } ``` React Query handles merging pages, tracking cursors, and managing the loading state for each page individually — no custom reducer required. ## The DevTools The `@tanstack/react-query-devtools` package adds a floating panel to your app in development that shows: - Every active query and its current state (`fresh`, `stale`, `fetching`, `paused`, `inactive`) - The full cache contents, inspectable in real time - The ability to manually trigger refetches, invalidations, or resets - Query timing and observer counts For debugging caching behavior — especially as applications grow — the DevTools are indispensable. They make the invisible cache visible. ## React Query vs. The Alternatives | Feature | React Query | SWR | Redux Toolkit Query | Apollo Client | |---|---|---|---|---| | **Protocol** | Any | Any | Any | GraphQL only | | **Cache control** | Fine-grained | Basic | Fine-grained | Fine-grained | | **Mutations** | First-class | Manual | First-class | First-class | | **Optimistic updates** | Built-in | Manual | Built-in | Built-in | | **Infinite queries** | Built-in | Built-in | Manual | Manual | | **DevTools** | Excellent | Basic | Redux DevTools | Apollo Studio | | **Bundle size** | ~13 kB | ~4 kB | Included in RTK | ~30 kB | | **Learning curve** | Moderate | Low | Moderate (Redux) | High | **SWR** (by Vercel) is React Query's closest competitor. It's lighter and simpler, making it a strong choice for smaller projects or Next.js apps with basic fetching needs. React Query wins in complex scenarios requiring fine-grained cache control, rich mutation lifecycle hooks, or sophisticated pagination. **Redux Toolkit Query (RTK Query)** is a strong contender if you're already using Redux. It integrates tightly with the Redux store and DevTools. If you're not already on Redux, the overhead of adopting it for server state alone is rarely justified. ## When Should You Use React Query? React Query shines in applications with: - **Multiple components that share the same remote data** — the deduplication and cache sharing alone justify adoption - **Complex mutation flows** — especially when mutations affect multiple queries - **UX requirements for perceived performance** — stale-while-revalidate makes apps feel instant - **Pagination or infinite scroll** — `useInfiniteQuery` is genuinely excellent - **Real-time or frequently-updated data** — polling and background refetch are first-class features You might *not* need React Query if: - You're building a mostly static site with minimal fetching (Next.js Server Components may be sufficient) - You have a single fetch at the top of your tree with no sharing or caching requirements - You're already deeply invested in an Apollo + GraphQL setup ## A Note on Next.js App Router With the Next.js App Router and React Server Components (RSC), some of the problems React Query solves can be addressed server-side: you can fetch data directly in Server Components without any client-side state management. However, React Query remains highly relevant for: - **Client-side interactivity**: data that changes based on user actions (filters, searches, pagination) - **Mutations**: `useMutation` is not replicated by RSC - **Real-time updates**: polling, refetch-on-focus, and WebSocket integration - **Shared client state**: when multiple client components need the same data The two paradigms are complementary. Fetch static or initial data on the server; use React Query for dynamic, interactive, and mutation-heavy workflows on the client. ## Conclusion React Query doesn't add a new paradigm to React — it completes the one that was already there. React handles UI state beautifully. React Query handles server state with the same elegance. The cognitive overhead of data fetching — loading states, error handling, caching, deduplication, retries, invalidation — dissolves into a handful of well-designed hooks. Your components become leaner. Your bugs become fewer. Your users see faster, more consistent UIs. If you're writing `useEffect` + `useState` to fetch data in 2025, you're solving a problem that's already been solved. React Query is the solution the community converged on — and for good reason. Start with `useQuery`. Add `useMutation` when you need to write. Let the cache do the rest. *Resources: [TanStack Query Docs](https://tanstack.com/query/latest) · [TanStack Query GitHub](https://github.com/TanStack/query) · [Practical React Query by TkDodo](https://tkdodo.eu/blog/practical-react-query)*

Articles tagged “State Management”

What is React Query and Why You Should Use It?