[TanStack Query] 서버 상태 관리 라이브러리

안녕하세요

오늘은 서버 상태 관리 라이브러리인 TanStack Query에 대해 정리해보고자 합니다.

 

 

🔽 TanStack Query

TanStack Query(이전 명칭 : react-query)는 웹 애플리케이션에서 서버 상태를 가져오고, 캐싱하고, 동기화하고, 업데이트하는 작업을 아주 쉽게 해줍니다.

 

 

🔽 왜 사용하는 가? (Why?)

클라이언트 상태(useState, useReducer)와는 달리, 서버에서 가져온 데이터는 시간이 지나면 바뀔 수 있고, 언제든 다시 가져와야 할 필요가 있습니다.

하지만 전통적인 방식(예: useEffect + axios + useState)으로 이걸 처리하려면 다음과 같은 문제가 발생합니다:

 

 

❌ 기존 방식의 문제점

• loading, error, data 상태를 직접 관리해야 함
• 컴포넌트가 언마운트되면 fetch 중단 처리 필요함
• 새로고침이나 다른 페이지에서 돌아왔을 때 데이터 재사용이 어려움
• 중복 fetch 발생하거나, refetch 타이밍 관리가 어려움

 

⭕️ TanStack Query의 해결 방안

: TanStack Query는 다음과 같은 서버 상태 관리의 반복적인 문제들을 자동으로 처리해줍니다:

• useQuery 하나로 로딩/에러/데이터 상태 자동 관리
• 캐시를 통해 데이터를 재사용하고, 필요할 때만 refetch
• 자동 리페치, 백그라운드 동기화, 무한 스크롤, mutation 관리까지 지원
• Suspense, Devtools 등과도 자연스럽게 통합 가능

 

 

🔽 어떻게 사용하는 가? (How?)

• TanStack Query를 사용하기 위해선 기본적으로 세 가지가 필요합니다:
  1. QueryClient 생성
  2. QueryClientProvider로 앱 감싸기
  3. `useQuery`로 데이터 가져오기

 

• ex. 사용자 리스트 불러오기

// 1. 기본 세팅 (index.tsx)
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'

const queryClient = new QueryClient()

<React.StrictMode>
  <QueryClientProvider client={queryClient}>
    <App />
  </QueryClientProvider>
</React.StrictMode>

// 2. useQuery 사용 예시
import { useQuery } from '@tanstack/react-query'
import axios from 'axios'

const fetchUsers = async () => {
  const { data } = await axios.get('https://jsonplaceholder.typicode.com/users')
  return data
}

function Users() {
  const { data, isLoading, error } = useQuery({
    queryKey: ['users'],
    queryFn: fetchUsers,
  })

  if (isLoading) return <p>Loading...</p>
  if (error) return <p>Error!</p>

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

 

 

 

 

 

 

🔽 어디서 사용하는 가? (Where?) 

그렇다면 이 TanStack Query는 어떤 문제에 적합한 도구인가?가 질문이야.

 

 

⭕️ 어디서 사용하는게 좋을까?

• 서버 상태(Server State)를 다룰 때 사용합니다.
• 즉, 외부 API나 DB에서 데이터를 가져오는 작업에서 강력한 이점을 발휘합니다.

 

• 사용하기 좋은 상황 예시:
  • GET /api/users, GET /api/posts처럼 읽기 기반 요청이 많을 때
  • 같은 데이터를 여러 컴포넌트에서 공유하거나, 다시 사용해야 할 때
  • 데이터가 자주 바뀌지 않지만 항상 최신 상태로 유지하고 싶을 때
  • 페이지를 이동했다가 다시 돌아왔을 때 캐시된 데이터로 빠르게 보여주고 싶은 경우
  • 스크롤에 따라 데이터를 점진적으로 불러오는 무한 스크롤 / 페이지네이션

 

❌ 어디서 사용하면 안될까?

• 클라이언트 상태(Client State)를 사용할 때는 적합하지 않다.
• ex. 모달 열림 여부, 입력창 내용, 테마 설정 등 사용자 인터랙션에 따라 변화하는 상태

• 사용하지 않는 게 나은 경우:
  • isModalOpen, formInputValue, isSidebarCollapsed 같은 UI 상태
  • 짧은 생명주기를 가지는 local 상태
  • 단순한 toggle, step 등 로컬 단위 조건 처리

 

 

🔽 한줄 요약

• TanStack Query는 서버에서 데이터를 가져오고 캐싱하며 상태를 자동으로 관리해주는 React용 라이브러리다.
• useEffect 없이도 로딩, 에러, 리페치 같은 반복 작업을 선언적으로 처리할 수 있어 생산성과 안정성이 높아진다.
• 서버 상태를 다루는 페이지, 리스트, 상세보기 등에서 특히 유용하며, 클라이언트 UI 상태에는 사용하지 않는다.