[설계 문서] Zustand? Tanstack Query? 전역 상태 관리 라이브러리 선정하기

이번 상태 관리 도구 선정 과정에서 여러 가지 중요한 점을 배울 수 있었습니다. 먼저 튜닝 서비스처럼 실시간 매칭, 채팅, 피드 등 다양한 상태를 동시에 관리해야 하는 구조에서는 단순히 기능만 많은 라이브러리보다 사용성과 유지보수 용이성이 중요하다는 것을 다시 느꼈습니다.

Zustand는 단일 훅 기반으로 직관적인 API와 작은 번들 크기를 제공해 빠른 개발과 코드 가독성을 확보할 수 있었고, 비동기 처리와 React 통합이 자연스러워 실시간 상태 관리에 매우 적합했습니다.

서버 상태 관리 도구로는 TanStack Query를 선택하며, 자동 캐싱, refetch, query invalidation 등 반복적인 API 통신을 라이브러리 수준에서 최적화할 수 있다는 점이 큰 장점이라는 것을 알게 되었습니다. 직접 Redux-thunk나 fetch 관리 로직을 구현하지 않고도 SSR, React 18 Concurrent 모드, Next.js App Router 환경에서 안정적으로 동작할 수 있다는 점에서 선택의 이유가 명확해졌습니다.

상태 관리 도구는 단순 성능이나 기능뿐만 아니라 서비스 구조, 팀 협업, 유지보수, 최신 기술 스택 호환성까지 고려해야 한다는 것을 배웠습니다. 또한 버전 선택 시 호환성, 안정성, 최신 기능 지원 여부를 꼼꼼히 검토하는 것이 서비스 장기 운영에 매우 중요하다는 점도 느꼈습니다. 앞으로 상태 관리 도구를 설계하고 도입할 때 보다 전략적으로 판단할 수 있는 기준을 마련하는 계기가 되었습니다.

---

4. Zustand 5.0.3

4-1. 전역 상태 관리 라이브러리 선정 이유

• 튜닝 서비스는 실시간 매칭, 채팅, 피드 등 다양한 상태를 관리해야 하는 구조로, 복잡한 redux의 구조보다 간단하고 유연한 상태 관리 도구가 적합합니다.
• Zustand는 단일 훅 기반의 상태 관리를 제공하여 컴포넌트 간 상태 공유가 용이하고 상태 업데이트가 직관적입니다.
• 또한 비동기 작업을 간단하게 처리할 수 있는 구조를 가지고 있어, 서버와의 통신이 빈번한 서비스에 적합하다. 실제 코드를 비교해보면 간결하고 가독성이 뛰어나며, 사용 경험이 많은 zustand를 선정하게 되었습니다.
• 우아한 형제들에서도 zustand와 tanstack-query를 함께 사용하는 구조를 도입했습니다. (우아콘 2023 프론트엔드 상태관리 실전 편 with React Query & Zustand)

---

4-2. Zustand / Redux 비교

항목	Zustand ⭐️	Redux (Toolkit)
설정 및 학습 곡선	단일 훅 기반, 설정 간단, 러닝 커브 낮음	액션, 리듀서, 미들웨어 등 개념 필요, 러닝 커브 높음
보일러플레이트	거의 없음 (단일 create()로 상태 정의)	액션 / 리듀서 / 스토어 분리 필요
성능 및 번들 크기	1KB 미만 gzipped, 빠른 렌더링 최적화	상대적으로 무거움, 미들웨어 사용 시 성능 저하 가능
React 통합성	useStore() 훅으로 컴포넌트에서 직접 상태 접근 가능	Provider로 앱 감싸야 하며, useSelector, useDispatch 등 별도 훅 사용 필요
비동기 처리	set() 내에서 직접 처리 가능, 미들웨어 없이도 유연하게 구현 가능	미들웨어 (redux-thunk, redux-saga) 필요
디버깅 도구	Redux DevTools 지원	Redux DevTools 및 다양한 미들웨어 지원

→ Zustand는 간단한 설정, 직관적인 API, 작은 번들 크기 등의 장점을 가지고 있어, 빠른 개발과 유지보수가 필요한 우리 서비스에 적합한 상태 관리 도구입니다. 특히, 실시간 데이터 처리와 비동기 작업이 많은 구조에서 유연하게 상태를 관리할 수 있고, React의 훅과 자연스럽게 통합되어 있어 개발 생산성을 높일 수 있습니다.

---

4-3. 버전 선택 - Zustand v5.0.3

항목	Zustand 4.0	Zustand 5.0.3 ⭐️
React 지원 버전	React 17 이상	React 18 이상
TypeScript 최소 버전	TypeScript 4.1 이상	TypeScript 4.5 이상
ES5 지원	지원	지원 중단 (ES6 이상)
기능 변경	다양한 기능과 미들웨어 지원	불필요한 기능 제거로 번들 크기 감소 및 유지보수 용이성 향상

 

Zustand v5.0.3은 불필요한 기능을 제거하여 번들 크기를 줄이고, React 18 및 TypeScript 4.5 이상을 지원하여 최신 기술 스택과의 호환성을 보장한다는 장점이 있습니다. 가장 최신에 나온 버전이지만, 공식 마이그레이션 가이드로 업데이트를 지원하는 만큼 안정성이 보장되었다. 따라서 Zustand 5.0.3을 도입하기로 결정했습니다.

---

5. Tanstack Query 5

5-1. 서버 상태 관리 라이브러리 선정 이유

• 매칭 리포트, 피드, 프로필 정보 등 서버 데이터와 지속적으로 통신하는 구조입니다. 이처럼 외부 API와의 연동이 많은 구조에서는 서버 상태를 효율적으로 캐싱하고 갱신할 수 있는 라이브러리가 필요합니다.
• TanStack Query는 서버 데이터를 클라이언트에서 자동 캐싱, 리패칭, 오류 처리, 로딩 상태 관리까지 통합 지원하며, React와 자연스럽게 통합되는 쿼리 훅 기반의 API를 제공합니다.
• 복잡한 Redux-thunk나 직접적인 fetch 관리 없이도 간결하게 API 통신 흐름을 제어할 수 있으며, 자동 refetch, query invalidation 같은 기능은 피드 콘텐츠 및 실시간 매칭 데이터 처리에 매우 유리합니다.
• 실제로 우아한 형제들, 카카오페이 등의 대규모 서비스에서도 react-query(= TanStack Query) 조합을 도입하여 실시간성과 상태 복잡도가 높은 구조를 효과적으로 관리하고 있습니다. (카카오페이 / 우아한형제들)

---

5-2. 서버 상태 관리 도구 비교

항목	TanStack Query ⭐️	Redux Toolkit (with Thunk)	SWR
캐싱 / Re-fetching	자동	수동 처리 필요	자동
Query Key 기반 상태 분리	지원	수동으로 분기 처리	단순 키 기반 캐시
로딩 / 에러 상태 관리	훅 내부에서 자동 관리	개발자가 수동 처리	내부에서 간편하게 처리 가능
개발자 경험	useQuery / useMutation 기반 API, 매우 직관적	boilerplate 많음	useSWR 등 간단함
SSR 대응	Next.js 공식 예시 존재, Hydration 지원	별도 처리 필요	기본은 CSR (SSR 시 별도 구성 필요)
Next.js 사용 적합성	매우 적합	직접 구현 필요	CSR 중심이라 일부 한계 있음

→ TanStack Query는 서버 상태 관리에 최적화된 라이브러리로, 불필요한 fetch 중복 방지, 성능 최적화, UX 개선을 한 번에 달성할 수 있어 실시간 피드 구조에 적합합니다.

---

5-3. 버전 선택 - TanStack Query v5

항목	TanStack Query v4	TanStack Query v5 ⭐️
React 버전 요구사항	React 16 이상	React 18 이상 권장
기본 Query Client 구조	Legacy 방식	createQuery, createMutation 등으로 API 개선
서버 컴포넌트 / SSR 최적화	미지원 / 제한적	Hydration, Suspense 기반 SSR 지원 강화
React 18 Concurrent 모드 호환성	제한적	정식 지원

 

→ TanStack Query v5은 React 18과 Next.js 15의 App Router, 서버 컴포넌트 환경에서 가장 적합하게 작동하는 버전이며, 자동 캐싱 최적화, 비동기 UI 흐름 구성, SSR 대응 등에서 우수한 성능을 보여줍니다. 공식 문서 및 예제도 지속적으로 관리되고 있으며, 복잡한 API 로직을 단순화할 수 있어 서비스에 가장 적합한 서버 상태 관리 도구로 선택했습니다.