llm-wiki/vault/20-evidence/official-docs/tanstack-query-server-state-official.md

title, source_type, url, archive_url, status, confidence, tags, related_projects, related_branches, created, last_reviewed

title	source_type	url	archive_url	status	confidence	tags	related_projects	related_branches	created	last_reviewed
TanStack Query — Server State Fetching, Caching & Synchronization Overview	official-doc	https://tanstack.com/query/latest/docs/framework/react/overview		raw	high	official-doc ca-skeleton frontend caching react	ca-skeleton-frontend		2026-07-18	2026-07-18

TanStack Query — Server State Fetching, Caching & Synchronization Overview

Layer: raw/official-docs/ — TanStack Query (구 React Query) 공식 문서(Overview / Motivation 섹션)의 원문 발췌. ca-skeleton-frontend 의 server-state 캐싱 계약(어떤 라이브러리로 fetch/cache/staleness 를 관리할지) 결정의 근거 자료.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/project-notes/ca-skeleton-frontend-operational-contract	server-state(원격 데이터) 관리를 client-state 라이브러리(Redux/Zustand 등)나 수기 useEffect+fetch 로 하지 않고 TanStack Query 같은 전용 캐싱 레이어로 하는 결정의 공식 근거. server-state 의 정의(원격 소유·비동기·stale 가능)와 caching/dedupe/background-refetch 를 라이브러리가 "직접 풀어야 할 문제"로 명시한다는 점을 인용.

특정 sub-branch (예: 실제 queryClient 설정, staleTime 정책)는 아직 branch-note 로 분해되지 않음. 현재는 project-note foundational 조사 단계의 근거로만 연결.

출처 / Source

• 원본 URL: https://tanstack.com/query/latest/docs/framework/react/overview
• 아카이브 URL: (미수집)
• 저자 / 조직: TanStack (오픈소스 프로젝트, 원 저자 Tanner Linsley)
• 발행일: 명시 없음 — /latest/ 버전 롤링 문서 (버전 고정 스냅샷 아님, 향후 문구 변경 가능)
• 마지막 확인일: 2026-07-18

왜 저장했는지 / Why archived

ca-skeleton-frontend 가 서버에서 가져온 데이터(목록/상세 등)를 어떻게 캐싱·재검증할지 결정할 때, "왜 수기 캐싱이 아니라 TanStack Query 인가"를 공식 문서로 뒷받침하기 위함. server-state 와 client-state 의 구분, 그리고 caching·dedupe·background refetch 를 라이브러리가 명시적으로 "풀어야 할 문제"로 나열한다는 점이 핵심 근거.

핵심 인용 / Key quotes (verbatim, 5문장/구절)

[Overview, 정의 문장] "TanStack Query (formerly known as React Query) is often described as the missing data-fetching library for web applications, but in more technical terms, it makes fetching, caching, synchronizing and updating server state in your web applications a breeze."

[Motivation] "Most core web frameworks do not come with an opinionated way of fetching or updating data in a holistic way."

[Motivation, server state 특성 목록 중] "Can potentially become "out of date" in your applications if you're not careful"

[Motivation, 문제 목록 중] "Caching... (possibly the hardest thing to do in programming)"

[Motivation, 문제 목록 중] "Updating "out of date" data in the background"

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
TSQ-C1	TanStack Query 는 스스로를 "missing data-fetching library" 로 정의하며, 핵심 기능을 fetching·caching·synchronizing·updating server state 로 명시한다 — 범용 client-state 매니저가 아니라 server-state 전용 도구로 자기 정의함	[Overview] "...it makes fetching, caching, synchronizing and updating server state in your web applications a breeze."	official-vendor-doc	ca-skeleton-frontend 가 "왜 server-state 를 위해 별도 라이브러리를 쓰는가"의 정의적 근거	이 문장만으로 TanStack Query 가 SWR·Apollo Client 등 대안보다 우월하다는 것은 증명 안 됨 — 비교는 별도 조사 필요
TSQ-C2	공식 문서는 "대부분의 핵심 웹 프레임워크는 데이터 fetch/update 를 총체적(holistic)으로 처리하는 opinionated 방법을 기본 제공하지 않는다"고 명시 — 즉 React 자체(또는 유사 프레임워크)에는 이런 계약이 없음을 전제로 깔고 있음	[Motivation] "Most core web frameworks do not come with an opinionated way of fetching or updating data in a holistic way."	official-vendor-doc	"React 만으로는 서버 데이터 fetch/cache 정책이 opinionated 하게 강제되지 않는다"는 전제의 근거	ca-skeleton-frontend 의 기존 수기 fetch 코드가 구체적으로 어떤 결함을 가졌는지는 증명 안 됨 — 프로젝트 코드 자체 감사 필요
TSQ-C3	공식 문서는 server state 의 특성 중 하나로 "조심하지 않으면 out of date(stale) 상태가 될 수 있다"는 점을 명시 — client state 와 달리 server state 는 구조적으로 staleness 문제를 갖는다는 것을 공식적으로 규정	[Motivation] "Can potentially become "out of date" in your applications if you're not careful"	official-vendor-doc	server-state vs client-state 구분에서 "staleness 는 server-state 고유 문제"라는 주장의 근거	이 문구만으로 TanStack Query 의 default staleTime 값이나 구체적 refetch 트리거 조건은 증명되지 않음 — 별도 "Important Defaults" 문서 확인 필요
TSQ-C4	공식 문서는 caching 을 "possibly the hardest thing to do in programming"(프로그래밍에서 가장 어려운 일 중 하나일 수 있다)라고 명시적으로 표현하며, server-state 를 다루게 되면 필연적으로 마주치는 문제 목록의 첫 항목으로 caching 을 든다	[Motivation] "Caching... (possibly the hardest thing to do in programming)"	official-vendor-doc	"caching 을 직접 구현하기보다 검증된 라이브러리에 위임한다"는 결정의 정성적 근거	이 문구는 캐싱의 어려움에 대한 프로젝트의 일반적 수사(修辭)이며, TanStack Query 자체 캐시 구현이 버그 없음을 증명하지 않음. 정량적 벤치마크·성능 수치는 없음
TSQ-C5	공식 문서는 "out of date 데이터를 백그라운드에서 업데이트하는 것"을 TanStack Query 가 다루는 문제 목록에 명시적으로 포함 — background refetch(stale-while-revalidate 유사 동작)가 라이브러리의 명시적 설계 목표임을 확인	[Motivation] "Updating "out of date" data in the background"	official-vendor-doc	"백그라운드 refetch(스테일 데이터 자동 갱신)를 수기로 구현하지 않고 라이브러리에 위임한다"는 결정의 근거	이 문구는 background refetch 가 "다루는 문제"임을 말할 뿐, refetchOnWindowFocus/refetchInterval 등 구체 API·기본값·retry 정책까지는 증명하지 않음. 본 overview 페이지 발췌 범위에서는 retry(재시도) semantics 에 대한 문장을 찾지 못함 — 별도 페이지("Query Retries" 등) 확인 필요, 이 claim 만으로 retry 를 일반화하지 말 것

Usage Boundaries / 적용 경계

• 이 자료가 직접 증명하는 것:
  • TSQ-C1: TanStack Query 는 server-state(fetch/cache/sync/update) 전용 라이브러리로 자기 정의됨
  • TSQ-C2: 핵심 웹 프레임워크(React 포함)는 데이터 fetch/update 에 대한 opinionated holistic 기본 제공이 없다고 공식 문서가 전제함
  • TSQ-C3: server state 는 원격 소유·비동기·타인에 의한 변경 가능성으로 인해 구조적으로 stale 해질 수 있음이 공식적으로 규정됨
  • TSQ-C4: caching 이 프로그래밍에서 가장 어려운 문제 중 하나로 공식 문서가 명시함
  • TSQ-C5: 백그라운드에서 stale 데이터를 갱신하는 것이 라이브러리가 다루는 명시적 문제로 포함됨
• 이 자료가 증명하지 않는 것:
  • TanStack Query 가 SWR, Apollo Client, RTK Query 등 다른 server-state 라이브러리보다 낫다는 비교 우위 (본 페이지는 자기소개일 뿐, 경쟁 비교 없음)
  • 구체적 기본값(default staleTime, gcTime, retry 횟수/backoff 정책 등) — 이 overview/Motivation 발췌에는 없음. 별도 "Important Defaults" 공식 페이지 조사 필요
  • retry(재시도) semantics — 이번 fetch 범위에서 관련 verbatim 문장을 찾지 못함. fabrication 방지를 위해 retry 관련 claim 은 생성하지 않음
  • ca-skeleton-frontend 코드베이스에서 실제로 TanStack Query 가 채택·구현되었는지 여부 (이 자료는 채택 근거일 뿐, 구현 사실 증거 아님 — 구현 사실은 별도 branch-note/코드에서 actually-implemented 등급으로 검증)
• 내 프로젝트(ca-skeleton-frontend)에 적용하려면 추가 확인이 필요한 것:
  • 실제 QueryClient 설정값(staleTime/gcTime/retry) — TanStack Query "Important Defaults" 페이지 별도 fetch 필요
  • React 외 프레임워크 어댑터(Vue/Solid/Svelte) 차이 여부 — 본 문서는 /framework/react/ 경로이므로 React 어댑터 한정
  • 서버사이드 렌더링(SSR)/Next.js 통합 시의 hydration 관련 문서는 본 발췌 범위 밖

메모 / Notes

나중에 wiki로 옮길 때 참고할 짧은 메모. 검증되지 않은 내 추론은 여기 두지 않음.

• WebFetch 는 raw HTML 을 그대로 반환하지 않고 소형 모델이 처리한 결과를 반환하는 구조라, verbatim 신뢰도를 높이기 위해 "verbatim 그대로, blockquote 로" 를 명시한 프롬프트로 3회 분할 재요청함(정의 문장 / Motivation 섹션 / 나머지 특성 목록). 5개 인용 모두 self-grep(grep -nF) 통과.
• retry 관련 quote 부재는 "이 페이지에 없다"는 뜻이지 "TanStack Query 에 retry 기능이 없다"는 뜻이 아님 — 흔한 오해 소지, 별도 확인 전까지 단정 금지.
• 추가로 봐야 할 동일 출처 페이지: /query/latest/docs/framework/react/guides/important-defaults, /query/latest/docs/framework/react/guides/query-retries, /query/latest/docs/framework/react/guides/caching

Related / 관련

• 같은 주제 다른 official-doc: (아직 없음 — TanStack Query 관련 raw 자료 최초 등록)
• 이 자료를 인용한 wiki 요약: [[wiki/concepts/...]] (생성 시)