Skip to content
Tutorials Center
My learning

Topics

Lesson 1 of 38 ยท Getting Started

What Is TanStack Query?

Learn what TanStack Query (React Query) does, why server state is different from client state, and how a cache of async data replaces hand-written fetch code.

Almost every web app loads data from a server: a list of products, a user profile, a feed of messages. Writing that code by hand with useEffect and useState works for a demo, but it grows into a pile of loading flags, error flags, duplicate requests and stale screens. TanStack Query (formerly React Query) is a library that takes over this job. You describe what data you need, and the library fetches it, caches it, shares it between components, keeps it fresh and tells you its status.

This course teaches TanStack Query v5 with React, because React is its most common home. The same core also powers adapters for Vue, Solid, Svelte and Angular, so the ideas carry over.

The live examples in this course load the real @tanstack/query-core and @tanstack/react-query packages (pinned to version 5.105.0) from a CDN, so they run in your browser. Anything that needs a server or a build step is shown in read-only blocks.

Server state is not client state

Two kinds of state live in an app, and they behave very differently.

Client state is owned by the browser: whether a menu is open, what is typed in a form, which tab is selected. You create it, you change it, and nobody else can change it behind your back.

Server state is a copy of data that lives somewhere else. Think of it as a photograph of a database row. It has awkward properties:

  • Fetching it is asynchronous and can fail.
  • Someone else can change the real data, so your copy can silently become out of date (stale).
  • Many components often need the same copy.
  • Updating it means sending a request and then deciding what to do with your copy.

State libraries such as Redux or Zustand are designed for client state. TanStack Query is designed for server state. In practice, once the server data is handled by Query, most apps find that very little client state is left.

flowchart LR
  A["Component A"] -->|"useQuery(['todos'])"| C["Query cache"]
  B["Component B"] -->|"useQuery(['todos'])"| C
  C -->|"one request"| S["Server"]
  S -->|"JSON"| C

Two components ask for the same data. The cache sends one request and gives both the same result.

What you get for free

What Query handles for you

Caching Data is stored by key and reused.
Deduplication Same request, sent once.
Refetching Stale data refreshes in the background.
Status Loading, error and success are tracked.
1 / 2

The core without React

The heart of the library is QueryClient, a plain JavaScript class with no React in it. Below, we use it directly. The queryKey identifies the data, and the queryFn is any function that returns a promise. Watch how the second call is answered from the cache instead of calling the function again.

JS QueryClient without React

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Only one request was made. The second fetchQuery found fresh data under the key ["user", 1] and returned it right away. You will meet staleTime properly in Stale Time and gc Time.

The same idea in React

In React you rarely touch QueryClient directly. You wrap the app in a provider and call the useQuery hook. The example below has two components that ask for the same key. Count the requests in the console.

Two components, one request

Both components render the same text, but the console shows a single request. The two useQuery calls became two observers of one cache entry.

What TanStack Query is not

  • It is not a fetching library. It does not make HTTP requests itself. You bring fetch, Axios, a GraphQL client or even a function that reads a local database, as long as it returns a promise.
  • It is not a global store for UI state. Keep modal flags and form drafts in useState or another client-state tool.
  • It is not required everywhere. A page that loads data once and never changes it may not need it.

A first look at the data flow

sequenceDiagram
  participant UI as Component
  participant Q as Query cache
  participant API as Server
  UI->>Q: useQuery(key, fn)
  Q-->>UI: status pending
  Q->>API: call fn
  API-->>Q: data
  Q-->>UI: status success + data
  Note over Q: data is cached under the key

The component never talks to the server. It only talks to the cache.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which description fits server state best?

    Server state is a copy of data owned elsewhere, so it is asynchronous and can go out of date. The other options are client state.
  2. 2. Does TanStack Query send HTTP requests by itself?

    Query manages the lifecycle of async data. The query function can use any tool, as long as it returns a promise.
  3. 3. Two components call useQuery with the same query key at the same time. How many requests are sent?

    Requests for the same key are deduplicated; both components observe the same cache entry.
  4. 4. Which package contains the framework-independent core?

    query-core has QueryClient and the cache. The React package adds hooks and the provider on top of it.

Summary

  • Server state is a cached copy of remote data. It is async, shared and can go stale.
  • TanStack Query caches by query key, deduplicates requests and refetches stale data.
  • A queryFn is any function returning a promise. Query does not do the HTTP itself.
  • QueryClient is the framework-free core; useQuery is the React hook on top.

Next: Installing and Setting Up