TanStack Query의 gcTime과 staleTime 비교

TanStack Query(React Query)에서 gcTime과 staleTime은 캐싱 전략을 제어하는 서로 다른 목적을 가진 옵션입니다.

사용할 때마다 헷갈리는 두 개념 정리해보겠습니다.

staleTime (신선도 시간)

데이터가 "신선한(fresh)" 상태로 유지되는 시간을 의미합니다.

• 기본값: 0 (즉시 stale 상태가 됨)
• 역할: 이 시간 동안은 데이터가 fresh 상태로 간주되어, 같은 쿼리를 다시 호출해도 네트워크 요청을 하지 않고 캐시된 데이터를 반환합니다.
• 사용 예시: 자주 변경되지 않는 데이터(예: 사용자 프로필, 설정값)는 staleTime을 길게 설정

const { data } = useQuery({
  queryKey: ['user', userId],
  queryFn: fetchUser,
  staleTime: 5 * 60 * 1000, // 5분 동안 fresh 상태 유지
});

gcTime (가비지 컬렉션 시간)

사용되지 않는 캐시 데이터가 메모리에서 제거되기까지의 시간입니다.

• 기본값: 5분 (300,000ms)
• 이전 이름: cacheTime (v5에서 gcTime으로 변경됨)
• 역할: 쿼리가 더 이상 활성 observer가 없을 때(언마운트 등), 이 시간 동안 캐시를 메모리에 보관합니다. 이 시간이 지나면 가비지 컬렉션 대상이 됩니다.
• 사용 예시: 사용자가 페이지를 왔다갔다 할 때 빠른 재접근을 위해 캐시 유지

const { data } = useQuery({
  queryKey: ['posts'],
  queryFn: fetchPosts,
  gcTime: 10 * 60 * 1000, // 10분 동안 캐시 유지
});

주요 차이점

구분	staleTime	gcTime
목적	데이터 신선도 판단	메모리 관리
영향	리페칭 여부 결정	캐시 삭제 시점 결정
기본값	0ms	5분
측정 시작	데이터 fetch 시점부터	마지막 observer 제거 시점부터(언마운트 시점)

실전 사용 패턴

// 1. 거의 변하지 않는 정적 데이터
const { data: categories } = useQuery({
  queryKey: ['categories'],
  queryFn: fetchCategories,
  staleTime: Infinity, // 절대 stale 상태가 되지 않음
  gcTime: 10 * 60 * 1000, // 10분간 캐시 보관
});

// 2. 실시간성이 중요한 데이터
const { data: notifications } = useQuery({
  queryKey: ['notifications'],
  queryFn: fetchNotifications,
  staleTime: 0, // 항상 stale (기본값)
  gcTime: 0, // 즉시 삭제
});

// 3. 균형잡힌 설정
const { data: posts } = useQuery({
  queryKey: ['posts'],
  queryFn: fetchPosts,
  staleTime: 30 * 1000, // 30초간 fresh
  gcTime: 5 * 60 * 1000, // 5분간 캐시 유지
});

일반적으로 staleTime ≤ gcTime 관계를 유지하는 것이 좋습니다.
staleTime이 gcTime보다 크면 데이터가 fresh 상태인데 캐시에서 삭제되는 비효율이 발생할 수 있습니다.

상태가 fresh인데 캐시가 없는경우 다시 refetch해야합니다.

체크 순서

페이지 마운트
↓
[1] 캐시 있음?
↓ YES
[2] fresh 상태? (staleTime 체크)
↓ NO (stale)
[3] 캐시 데이터 즉시 반환
↓
[4] 백그라운드 리페칭 시작
↓
[5] 새 데이터 도착 시 업데이트

결과

stale 상태여도 캐시가 있으면 캐시데이터를 즉시 보여주고(UX 좋음) + 뒤에서 업데이트(데이터 최신성 유지)하는 것이 TanStack Query의 강력한 장점입니다!