TanStack Query의 staleTime과 gcTime 차이

TanStack Query의 staleTime과 gcTime 차이

TanStack Query는 데이터 캐싱과 상태 관리를 효율적으로 처리하기 위한 강력한 라이브러리다.
그중에서도 staleTime과 gcTime은 데이터의 생명주기를 조절하는 핵심 설정이다.

---

staleTime 이란?

staleTime은 데이터를 가져온 후, 얼마 동안 신선한(fresh) 상태로 유지할지를 결정하는 시간이다.
즉, 이 시간이 지나기 전까지는 네트워크 요청 없이 캐시된 데이터를 그대로 사용한다.

useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
  staleTime: 1000 * 60 * 5, // 5분 동안 신선한 상태 유지
});

위 예시처럼 staleTime을 5분으로 설정하면, 데이터를 처음 가져온 후 5분 동안은 refetch가 트리거되더라도 서버 요청 없이 캐시 데이터를 재사용한다.

• 기본값: 0
• 의미: 0이면 데이터를 가져오자마자 즉시 오래된(stale) 상태로 간주한다.
• 활용: 서버 데이터가 자주 변하지 않는 경우, staleTime을 늘려 불필요한 네트워크 요청을 줄일 수 있다.

---

gcTime 이란?

gcTime은 해당 쿼리가 사용되지 않게 된 후 캐시에서 삭제되기까지의 시간을 의미한다. 즉, 컴포넌트가 언마운트된 이후에도 캐시 데이터를 얼마 동안 메모리에 남길지 결정한다.

useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
  gcTime: 1000 * 60 * 10, // 10분 후 캐시 삭제
});

예를 들어, gcTime을 10분으로 설정하면 컴포넌트가 언마운트된 이후에도 10분 동안 캐시 데이터가 메모리에 유지된다. 이 기간 내에 동일한 쿼리가 다시 사용되면 기존 캐시를 재활용하여 빠르게 데이터를 표시할 수 있다.

• 기본값: 5분
• 의미: 사용되지 않는 쿼리는 5분이 지나면 가비지 컬렉션(GC)에 의해 캐시에서 제거된다.
• 활용: 사용 빈도가 높은 데이터라면 gcTime을 길게 설정하여 재요청 비용을 줄일 수 있다.

---

💡 staleTime vs gcTime 요약 비교

개념	비유	동작 시점
staleTime	“이 음식은 5분 동안은 신선하니까 새로 만들 필요 없어!” 🍱	데이터를 fetch한 직후부터
gcTime	“이 음식은 냉장고에 10분 동안은 버리지 말고 보관하자!” 🧊	쿼리가 더 이상 사용되지 않을 때부터

즉,

• staleTime은 “데이터를 새로 가져올지 말지”를 결정하고,
• gcTime은 “캐시 데이터를 메모리에 남겨둘지 말지”를 결정한다.

---

Summary

staleTime과 gcTime을 적절히 설정하면 불필요한 네트워크 요청을 줄이면서도, 사용자 경험(UX)을 향상시킬 수 있다.

• 데이터가 자주 변경되지 않는다면 staleTime을 늘리고,
• 재방문 가능성이 높다면 gcTime을 길게 설정하자.

이 두 설정만으로도 캐싱 전략의 효율성이 크게 달라진다.

---

Reference

• TanStack Query 공식 문서

```

---

END