TanStack Query - (2) Setup 하기

 

이번 포스트에서는 TanStack Query를 프로젝트에 적용하고, 전역에서 사용할 수 있도록 셋업하는 과정을 알아보겠습니다.

 

1. 설치

먼저 아래 명령어를 입력해 TanStack Query와 개발 도구(Devtools)를 설치합니다.

npm i @tanstack/react-query

npm i @tanstack/react-query-devtools

• @tanstack/react-query: TanStack Query의 핵심 라이브러리로, 서버 상태 관리를 위한 기능들을 제공합니다.
• @tanstack/react-query-devtools: 개발 중 캐시 상태, 쿼리 상태 등을 시각적으로 확인할 수 있는 유용한 도구입니다.

 

 

2. QueryClient 생성

React 앱 전체에서 쿼리 기능을 사용하려면 QueryClient를 만들어 QueryClientProvider로 감싸주어야 합니다.
이 클라이언트는 TanStack Query가 내부적으로 상태를 관리하는 데 사용하는 중심 객체입니다.

 

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 60 * 1000, // 1분 동안은 데이터를 신선한 것으로 간주
    },
  },
});

 

staleTime: 데이터를 신선한 상태로 유지하는 시간입니다. 이 시간 동안은 같은 쿼리를 다시 호출해도 네트워크 요청을 하지 않습니다. UX를 부드럽게 만드는 중요한 설정입니다.

 

 

3. React 앱에 적용하기

이제 App 컴포넌트에서 QueryClientProvider로 애플리케이션 전체를 감싸주고, ReactQueryDevtools도 함께 추가해줍니다.

 

import { BrowserRouter, Navigate, Route, Routes } from "react-router-dom";

import GlobalStyles from "./styles/GlobalStyles";
import Dashboard from "./pages/Dashboard";
import Bookings from "./pages/Bookings";
import Cabins from "./pages/Cabins";
import Users from "./pages/Users";
import Settings from "./pages/Settings";
import Account from "./pages/Account";
import Login from "./pages/Login";
import PageNotFound from "./pages/PageNotFound";
import AppLayout from "./ui/AppLayout";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { ReactQueryDevtools } from "@tanstack/react-query-devtools";

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 60 * 1000,
    },
  },
});

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <ReactQueryDevtools initialIsOpen={false} />
      <GlobalStyles />
      <BrowserRouter>
        <Routes>
          <Route element={<AppLayout />}>
            <Route index element={<Navigate replace to='dashboard' />} />
            <Route path='dashboard' element={<Dashboard />} />
            <Route path='bookings' element={<Bookings />} />
            <Route path='cabins' element={<Cabins />} />
            <Route path='users' element={<Users />} />
            <Route path='settings' element={<Settings />} />
            <Route path='account' element={<Account />} />
          </Route>

          <Route path='login' element={<Login />} />
          <Route path='*' element={<PageNotFound />} />
        </Routes>
      </BrowserRouter>
    </QueryClientProvider>
  );
}

export default App;

 

이렇게 하면 프로젝트 어디서든 useQuery, useMutation 등의 훅을 사용할 수 있게 됩니다.

 

4. 라우팅 및 페이지 구성

이 포스트에서는 라우팅 구조까지 함께 설정되어 있습니다.
react-router-dom을 사용해 여러 페이지(Dashboard, Cabins, Users 등)를 정의하고, AppLayout을 통해 공통 UI 레이아웃을 구성하고 있습니다.

이 부분은 프로젝트에 따라 생략하거나 변경될 수 있습니다. 핵심은 QueryClientProvider가 루트 컴포넌트에 적용되어 있어야 한다는 점입니다.

---

✅ 정리

TanStack Query는 프로젝트의 루트에 클라이언트를 설정해주기만 하면,
이후부터는 어떤 컴포넌트에서도 간편하게 서버 데이터를 가져오고, 캐싱하고, 갱신할 수 있게 됩니다.

다음 포스트에서는 useQuery를 사용해서 실제 데이터를 가져오는 예제를 작성해보겠습니다.