Introduction to TanStack Query for Server State0%
Managing Pagination, Caching, and Background Refetch

Introduction to TanStack Query for Server State

Beginner12 min read•Updated: Jul 11, 2026
Study MaterialsCheatsheet

Introduction to TanStack Query for Server State

1. The Server State vs Client State Paradigm

In React development, engineers historically treated all data the same—dumping both UI state and fetched API data into useState, useReducer, or Redux.

However, modern engineering distinguishes between two fundamentally different types of state:

  1. 1
    Client State (UI State): Data wholly owned by the browser that is synchronous and always up-to-date (e.g. modal open/closed, active tab, form inputs).
  2. 2
    Server State (Remote Cache): Data owned by a remote server that is asynchronous, shared across multiple users, requires serialization, and can become stale at any moment without your knowledge (e.g. user profile, course list, stock prices).

Using raw useEffect and useState for server state forces you to manually write hundreds of lines for caching, deduplication, retry logic, background refetching, and pagination.

TanStack Query (formerly React Query) is the industry standard for managing server state in modern web applications.

Output
Traditional useEffect Data Fetching:
[Manual loading state] + [Manual error state] + [No caching] + [No auto-retry] + [Race conditions]
 
TanStack Query:
const { data, isLoading, error } = useQuery(...)
(Automatic caching, window-focus refetching, background updates, auto-retries!)

2. Installing TanStack Query

Bash / Terminal
npm install @tanstack/react-query

3. Setting Up QueryClientProvider

Wrap your application root with QueryClientProvider:

JSX
// src/main.jsx or src/App.jsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import App from './App.jsx';
 
// Create a query client instance
const queryClient = new QueryClient({
defaultOptions: {
queries: {
staleTime: 1000 * 60 * 5, // Data remains "fresh" for 5 minutes
retry: 2 // Automatically retry failed requests twice
}
}
});
 
ReactDOM.createRoot(document.getElementById('root')).render(
<React.StrictMode>
<QueryClientProvider client={queryClient}>
<App />
</QueryClientProvider>
</React.StrictMode>
);

4. Fetching Data with useQuery

To fetch and cache data, call the useQuery hook:

JSX
import React from 'react';
import { useQuery } from '@tanstack/react-query';
 
async function fetchCourses() {
const res = await fetch('/api/courses');
if (!res.ok) throw new Error('Network response was not ok');
return res.json();
}
 
export default function CourseDirectory() {
// queryKey uniquely identifies this cache entry
// queryFn is the promise-returning function
const { data: courses, isLoading, isError, error } = useQuery({
queryKey: ['courses'],
queryFn: fetchCourses
});
 
if (isLoading) return <div className="spinner">Fetching courses...</div>;
if (isError) return <div className="error-alert">Error: {error.message}</div>;
 
return (
<div className="course-list">
<h2>Active Courses ({courses.length})</h2>
<ul>
{courses.map(course => (
<li key={course.id}>{course.title}</li>
))}
</ul>
</div>
);
}

5. Superpowers Out of the Box

By adopting TanStack Query:

  • Automatic Caching: If two components request ['courses'], only one network request is sent!
  • Window Focus Refetching: When a user tabs back to your application after reading an email, TanStack Query automatically refreshes stale data in the background.
  • Deduplication: Multiple rapid calls are merged into a single network flight.
Interactive Quiz

Practice Quiz

Question 1
What is the primary difference between Client State and Server State?
Question 2
What are the two mandatory properties required when configuring useQuery?
Question 3
What happens by default when two separate components on the same screen both invoke useQuery({ queryKey: ['userData'], ... })?
Question 4
What does staleTime configure in TanStack Query?
Question 5
What component must wrap your application tree to enable TanStack Query hooks?
Next Lesson

Managing Pagination, Caching, and Background Refetch

Continue learning with hands-on practice, examples, and exercises in the upcoming topic.

Related Lessons

Previous LessonNext Lesson
Handling HTTP POST, PUT, and DELETE MutationsManaging Pagination, Caching, and Background Refetch

Practice Quiz

Test your understanding of this lesson with 5 questions. Each question has one correct answer.

PreviousNext
PrevNext