Getting Started with React Query (TanStack Query)

📅

loading..🐩🐩🐩🐩

Getting Started with React Query (TanStack Query) | PromleeBlog

Before We Begin 🔗

React web apps often need to fetch data from external APIs and display it. That means deciding how to fetch it, what to show while a request is loading or after it fails, and how to cache the response so you don't keep making the same request.

TanStack Query

helps with those tasks. Originally known as

React Query

, it has grown into a server-state library for multiple frameworks. We'll use React and work through examples from basic queries to more advanced caching patterns.

What Is TanStack Query? 🔗

TanStack Query helps client applications manage server state. It handles data returned by a server and simplifies loading states, errors, caching, and refetching.

For example, you can use it to:

Fetch posts from an API and show them on screen.
Cache the response to avoid repeating the same request.
Show a loading spinner while the request is pending.
Show an error message when the request fails.

Installation 🔗

Run the following command in your terminal to install TanStack Query.

npm install @tanstack/react-query

Set up QueryClientProvider at the root of your React app so its components can use queries.

// main.tsx 또는 App.tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
const queryClient = new QueryClient();
root.render(
  <QueryClientProvider client={queryClient}>
    <App />
  </QueryClientProvider>
);

Basic useQuery Usage 🔗

Let's start with the JSONPlaceholder posts endpoint (/posts).

import { useQuery } from '@tanstack/react-query';
import axios from 'axios';
 
const fetchPosts = async () => { // 정보를 fetch하는 함수
  const res = await axios.get('https://jsonplaceholder.typicode.com/posts');
  return res.data;
};
 
function PostList() {
  const { data, isLoading, isError, error } = useQuery({ // 쿼리 결과를 가져오는 컴포넌트
    queryKey: ['posts'], // 쿼리의 고유 식별자
    queryFn: fetchPosts, // 정보를 fetch하는 함수
  });
  
  if (isLoading) return <p>불러오는 중입니다...</p>;
  if (isError) return <p>오류가 발생했습니다: {(error as Error).message}</p>;
  return (
    <ul>
      {data.map((post: any) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  );
}

First, define an asynchronous function that fetches and returns the data.

Pass it to the queryFn option in useQuery.

The useQuery hook calls the function and caches its result.

Why Query Keys Matter 🔗

TanStack Query uses queryKey to identify requests, keep cache entries separate, and determine which queries to refetch.

Basic Usage 🔗

For a simple query, use a key that identifies the resource. The example below uses a string inside an array.

useQuery({
  queryKey: ['posts'],
  queryFn: fetchPosts,
});

If a request depends on API parameters, include them in the array.

useQuery({
  queryKey: ['user', userId],
  queryFn: () => fetchUser(userId),
});

Queries with different userId values then get separate cache entries.

Advanced Pattern: Nested Keys 🔗

For more complex queries, structure the queryKey hierarchically.

useQuery({
  queryKey: ['users', userId, 'posts'],
  queryFn: () => fetchUserPosts(userId),
});

This identifies the posts for a particular user and makes it easier to manage the cache.

Integrate with Suspense 🔗

React's Suspense and TanStack Query can work together to make loading states more declarative. Wrap the querying component in a Suspense boundary. The example uses the older useQuery option suspense: true. Check the API for your installed version before using it.

// App.tsx
<Suspense fallback={<p>로딩 중입니다...</p>}>
  <PostList />
</Suspense>

// PostList.tsx
const { data } = useQuery({
  queryKey: ['posts'],
  queryFn: fetchPosts,
  suspense: true,
});

This makes the component simpler and lets the surrounding boundary handle loading states. Add an ErrorBoundary to handle errors.

Use React Query Devtools 🔗

The devtools let you inspect queries as the app runs.

npm install @tanstack/react-query-devtools

import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
<QueryClientProvider client={queryClient}>
  <App />
  <ReactQueryDevtools initialIsOpen={false} />
</QueryClientProvider>

Use them to inspect cached data, query status, and request timing when debugging.

Use TanStack Query with Server-Side Rendering 🔗

In a framework like Next.js, you can prefetch queries on the server and include their data in the initial page payload to speed up initial rendering.

This example uses dehydrate and the older Hydrate component.

// 서버에서
const queryClient = new QueryClient();
await queryClient.prefetchQuery({ queryKey: ['posts'], queryFn: fetchPosts });
const dehydratedState = dehydrate(queryClient);

// 클라이언트에서
<Hydrate state={dehydratedState}>
  <App />
</Hydrate>

Hydrating the client with the server's cache lets it display the prefetched data without flashing a loading state.

Advanced Error Handling 🔗

When a query or mutation fails, you can notify the user or retry it. The examples include these options, whose availability can depend on the version:

retry controls automatic retries.
onError runs a callback after a failure where supported.
useErrorBoundary forwards errors to an error boundary in older versions.

useQuery({
  queryKey: ['posts'],
  queryFn: fetchPosts,
  retry: 2,
  onError: (error) => {
    toast.error('데이터를 불러오는 데 실패했습니다');
  },
});

Handle failures in useMutation similarly. You can also log errors to the console or report them to a service such as Sentry.

Conclusion 🔗

TanStack Query is a flexible tool for working with asynchronous data in React. Beyond basic useQuery and useMutation usage, it supports caching, invalidation, conditional queries, infinite scrolling, Suspense, and server-side rendering. These features simplify logic that would otherwise be complex to implement yourself.

Try applying the examples and strategies from this guide in a project.

References 🔗

Official TanStack Query documentation: https://tanstack.com/query↗
JSONPlaceholder API: https://jsonplaceholder.typicode.com↗