🚀 React Query → TanStack Query로 버전 통합하며 마주한 실전 이슈 정리

🧩 배경

닥터나우 프론트엔드 프로젝트에서는 과거부터 사용해오던 React Query v3와 신규 도입된 TanStack Query v4가 혼재되어 있었습니다.

두 버전이 공존하면서 다음과 같은 문제들이 발생했습니다.

 

• queryClient가 서로 달라서 쿼리 업데이트 및 상태 관리가 불안정
• 버전 간 API와 동작 방식이 달라 개발자가 로직을 예측하기 어려움
• 특히 약국 서비스에서 로그인 시 아무 요청도 가지 않는 현상 발생

---

🛠️ 전환 작업 진행

2025년 3월과 5월, 프론트엔드 전체에서 TanStack Query v4 기준으로 단일화하는 작업을 진행했습니다.

v3 → v4 전환은 공식 가이드를 기반으로 점진적으로 적용했고, 예상보다 큰 인터페이스 변화는 없어 전환 자체는 순조로웠습니다.

 

하지만 예상치 못한 실전 이슈는 따로 있었습니다.

---

🚨 겪은 이슈들

1. isLoading 관련 UI 오작동

enabled: false로 설정된 쿼리가 요청을 보내지 않음에도 불구하고

isLoading 값은 true로 반환되는 현상 발생.

→ 사용자 입장에서는 로딩 중처럼 보이지만 실제로는 아무 요청도 발생하지 않음.

 

2. loading 상태 재정의 필요

기존 로직에서 단순히 isLoading만으로 로딩 여부를 판단했던 부분들을 다음 기준으로 재정의했습니다:

• isInitialLoading: 쿼리 최초 요청 시 로딩 여부 판단에 사용
• → 단, keepPreviousData: true일 때만 안정적으로 동작
• isLoading && isFetching: 과거 데이터를 유지하지 않는 쿼리에서 재요청 시 로딩 판단용으로 사용

참조: https://github.com/TanStack/query/issues/3975#issuecomment-1245101647

 

3. 네트워크 상태에 따라 요청이 차단됨

v4부터는 기본적으로 네트워크 상태가 offline이면 요청이 자동으로 차단됨.

v3와 혼용 상태에서는 이 조건이 예상치 못한 이슈로 이어졌습니다.

 

→ 대응: 약사 웹에서 전면적으로 v4로 통합하고,

모든 query 및 mutation에 networkMode: 'always' 옵션을 설정하여

네트워크 상태와 무관하게 요청이 항상 발생하도록 처리

---

✅ 결과 (Output)

• 서버 데이터를 다루는 라이브러리의 단일화 완료
• → queryClient를 하나로 통일하여 상태 관리 안정성 확보
• 데이터 fetching 및 캐시 동작 일관성 확보
• → 이전에는 버전에 따라 결과가 달랐던 로직들이 명확해짐
• 로딩 처리 기준 정리 및 일괄 적용
• → UI 신뢰도 향상, 유지보수 용이성 증가
• 모든 요청에 대해 네트워크 상태 무관하게 요청 보장 설정(networkMode: ‘always’)
• → 오류 발생 시 디버깅 용이, 사용자 경험 개선
• 최신 메이저 버전인 TanStack Query v5로 업그레이드 가능한 기반 마련

---

📌 정리

React Query에서 TanStack Query로의 전환은 단순한 버전 업그레이드 그 이상이었습니다.

기능과 옵션은 유사하지만, 실제 동작 방식과 상태 처리 로직에서 생기는 작은 차이들이

실서비스에서 얼마나 민감하게 작용할 수 있는지를 체감한 사례였습니다.

 

이번 경험을 통해 아래와 같은 교훈을 얻었습니다.

• 단순한 마이그레이션도 실제 운영 서비스에서는 반드시 로직 단위의 검증이 필요
• isLoading, isFetching, isInitialLoading은 그 의미가 미묘하게 다름
• 쿼리 동작은 네트워크, 옵션, UI 렌더 조건이 복합적으로 맞물려야 정확히 작동

---

 

💬 마무리

라이브러리 전환은 기술 부채 해결의 출발점이자,

우리가 얼마나 해당 도구의 동작 원리와 상태 흐름을 제대로 이해하고 있는지를 되돌아보게 만드는 작업이었습니다.

 

앞으로 TanStack Query v5로의 전환도 예정되어 있는데,

이번 경험이 그 기반이 되리라 믿습니다.