TanStack Query

labbiel·2025년 10월 24일

TanStack Query

서버 상태를 효율적으로 관리하기 위한 라이브러리
주로 데이터 fetching, caching, synchronization, background update 등을 편리하게 처리

1. 핵심 개념

개념	설명
Server State	API 등 외부 서버에서 가져오는 데이터로, 로컬 상태(useState 등)와 달리 서버 환경 시 동기화가 필요
Query	데이터를 가져오는 비동기 함수를 의미
Mutation	데이터를 생성/수정/삭제하는 비동기 함수
Cache	요청 결과를 메모리에 저장해서 불필요한 재요청 방지
Query Key	각 요청을 구분하는 고유 식별자
Query Invalidation	데이터 변경 후 캐시된 데이터를 불러오게 하는 기능

2. 기본 사용

설치

npm install @tanstack/react-query

설정(QueryClientProvider)


// App.tsx
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import React from "react";
import ReactDOM from "react-dom/client";
import App from "@/App";

const queryClient = new QueryClient();


ReactDOM.createRoot(document.getElementById("root")!).render(
  <QueryClientProvider client={queryClient}>
    <App />
  </QueryClientProvider>
);

3. 데이터 조회(useQuery)

import { useQuery } from "@tanstack/react-query";
import axios from "axios";

function Users() {
  const { data, isLoading, isError } = useQuery({
    queryKey: ["users"],
    queryFn: async () => {
      const res = await axios.get("https://jsonplaceholder.typicode.com/users");
      return res.data;
    },
  });

  if (isLoading) return <p>로딩 중...</p>;
  if (isError) return <p>에러 발생!</p>;

  return (
    <ul>
      {data.map((user) => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}

특징

캐시되어 같은 key로 다시 요청해도 네트워크 요청 없이 즉시 반환
새로고침 시 자동으로 refetch
백그라운드에서 최신화

4. 데이터 변경(useMutation)

import { useMutation, useQueryClient } from "@tanstack/react-query";
import axios from "axios";

function AddUser() {
  const queryClient = useQueryClient();

  const mutation = useMutation({
    mutationFn: (newUser) =>
      axios.post("https://jsonplaceholder.typicode.com/users", newUser),
    onSuccess: () => {
      // users 데이터를 다시 가져오게 함
      queryClient.invalidateQueries(["users"]);
    },
  });

  const handleAdd = () => {
    mutation.mutate({ name: "새 사용자" });
  };

  return (
    <button onClick={handleAdd}>
      {mutation.isPending ? "등록 중..." : "사용자 추가"}
    </button>
  );
}

5. 캐싱 & 자동 업데이트 설정 예시

useQuery({
  queryKey: ["todos"],
  queryFn: fetchTodos,
  staleTime: 1000 * 60 * 5, // 5분 동안 캐시 유지
  cacheTime: 1000 * 60 * 10, // 10분 동안 캐시 보관
  refetchOnWindowFocus: false, // 창 포커스 시 재요청 비활성화
});

6. DevTools

npm install @tanstack/react-query-devtools

import { ReactQueryDevtools } from "@tanstack/react-query-devtools";

<QueryClientProvider client={queryClient}>
  <App />
  <ReactQueryDevtools initialIsOpen={false} />
</QueryClientProvider>