React에서 서버 상태를 다루기 편하게 해주는 TanStack Query

React로 화면을 만들다 보면 생각보다 많은 시간이 API 데이터를 다루는 데 쓰입니다. 데이터를 불러오고, 로딩 상태를 표시하고, 실패했을 때의 처리를 만들고, 다시 새로고침해야 하는 시점을 고민합니다. 처음에는 단순한 fetch 코드로 충분해 보이지만, 화면이 늘어나면 이 흐름이 금방 복잡해집니다.

TanStack Query, 예전 이름으로 React Query는 이 문제를 꽤 잘 정리해주는 도구입니다. React 애플리케이션에서 비동기 데이터, 특히 서버에서 가져오는 데이터를 가져오고, 캐싱하고, 동기화하고, 업데이트하는 일을 도와줍니다.

클라이언트 상태와 서버 상태는 다릅니다
React에서 상태라고 하면 보통 useState나 Zustand 같은 상태 관리 도구를 떠올립니다. 하지만 서버에서 가져온 데이터는 일반적인 화면 상태와 조금 다릅니다.

예를 들어 모달이 열려 있는지, 입력창에 어떤 값이 들어 있는지는 클라이언트 안에서만 관리하면 됩니다. 반면 게시글 목록, 사용자 정보, 알림 개수 같은 데이터는 서버에 원본이 있습니다. 화면에 보이는 값은 그 원본을 잠시 가져와 보여주는 캐시에 가깝습니다.

TanStack Query는 이 서버 상태를 다루는 데 집중합니다. 단순히 API를 호출하는 도구라기보다, 가져온 데이터의 생명주기를 관리해주는 도구에 가깝습니다.

반복되는 코드를 줄여줍니다
직접 API 호출 코드를 작성하면 보통 loading, error, data 상태를 따로 관리하게 됩니다. 같은 패턴이 여러 화면에 반복되고, 캐시를 직접 관리하려면 더 복잡해집니다.

TanStack Query를 사용하면 useQuery 훅으로 데이터를 가져오고, 로딩 여부나 에러 상태, 성공한 데이터를 함께 받을 수 있습니다. 같은 query key를 사용하는 데이터는 캐시로 관리되기 때문에, 이미 가져온 데이터를 다시 활용하기도 쉽습니다.

또한 서버 데이터를 변경하는 작업은 mutation으로 분리할 수 있습니다. 예를 들어 게시글을 등록하거나 삭제한 뒤, 관련 목록을 다시 불러오게 만드는 흐름도 Query Invalidation이라는 방식으로 정리할 수 있습니다.

작은 프로젝트에서도 장점이 있습니다
TanStack Query는 큰 서비스에서만 필요한 도구처럼 보일 수 있습니다. 하지만 작은 프로젝트에서도 장점이 있습니다. API 데이터 처리 방식이 일정해지기 때문입니다.

혼자 서비스를 만들 때는 새로운 기능을 빠르게 붙이는 것도 중요하지만, 나중에 다시 열어봤을 때 구조를 이해할 수 있어야 합니다. TanStack Query를 사용하면 “서버에서 가져온 데이터는 query로 관리한다”는 기준이 생깁니다. 이 기준 하나만으로도 코드가 덜 흩어집니다.

특히 목록, 상세, 저장, 삭제 같은 화면이 반복되는 관리자 페이지나 작은 SaaS 형태의 서비스에서는 체감이 큽니다. 매번 로딩 상태와 새로고침 시점을 직접 고민하지 않아도 되기 때문입니다.

그래도 모든 상태를 맡기는 도구는 아닙니다
TanStack Query를 사용할 때 주의할 점도 있습니다. 이 도구는 서버 상태를 다루는 데 강하지만, 모든 클라이언트 상태를 대신하는 도구는 아닙니다. 입력 폼의 임시 값, UI 토글, 화면 안에서만 쓰이는 상태는 여전히 React의 기본 상태나 다른 상태 관리 도구가 더 단순할 수 있습니다.

또 하나는 query key를 잘 정리해야 한다는 점입니다. 캐시는 query key를 기준으로 관리되기 때문에, 키 이름이 제각각이면 나중에 무효화하거나 다시 불러오는 흐름이 복잡해질 수 있습니다.

결국 TanStack Query를 잘 쓰려면 “이 데이터의 원본이 어디에 있는가”를 먼저 생각해야 합니다. 원본이 서버에 있다면 query로 관리하고, 화면 안에서만 의미가 있다면 로컬 상태로 두는 식입니다.

마무리
TanStack Query는 React에서 서버 데이터를 다루는 반복 작업을 줄여주는 실용적인 도구입니다. 데이터를 가져오고, 캐싱하고, 다시 동기화하고, 변경 후 관련 데이터를 갱신하는 흐름을 한 가지 방식으로 정리해줍니다.

저는 이런 도구가 작은 서비스에도 꽤 잘 맞는다고 느낍니다. 기능이 많아질수록 API 호출 코드는 자연스럽게 흩어지기 쉬운데, TanStack Query는 그 흐름을 다시 모아주는 기준이 됩니다.

물론 도구 하나가 설계를 대신해주지는 않습니다. 하지만 서버 상태와 클라이언트 상태를 구분하는 습관을 만들어준다는 점에서, React 프로젝트를 오래 관리하려는 사람에게는 한 번쯤 제대로 써볼 만한 선택지라고 생각합니다.