Tanstack Query staleTime, gcTime

🔄 staleTime (데이터 신선도)

staleTime은 데이터의 최신성 보장을 목표로 하는 설정입니다.

핵심 원칙

핵심은 “서버 데이터는 언제든 바뀔 수 있다.” 라는 원칙에서 출발합니다. 아무리 방금 가져온 데이터라도, 시간이 지나면 최신이 아닐 수 있다는 관점입니다.

동작 방식

데이터가 화면에 표시되고 있더라도, 설정된 staleTime (기본값은 0초)이 지나면 해당 데이터는 오래된 데이터 (stale) 로 간주됩니다. 이렇게 오래된 데이터로 간주되면, 사용자가 창을 다시 포커스하거나, 데이터를 사용하는 컴포넌트가 다시 마운트될 때 자동으로 데이터를 새로고침 (refetch) 하여 항상 최신 정보를 보여주려고 시도합니다.

실사용 예시

SNS 피드나 주식 차트와 같이 실시간성이 중요한 데이터에 유용합니다. 다른 탭을 보다가 서비스 탭으로 돌아왔을 때, 사용자가 별도의 새로고침 버튼을 누르지 않아도 최신 게시물이나 주식 가격이 자동으로 화면에 반영되도록 합니다.

---

🗑️ gcTime (캐시 보관 시간)

gcTime은 빠르고 부드러운 화면 전환을 목표로 하는 설정입니다. 이는 가비지 컬렉션(Garbage Collection) 시간을 의미합니다.

핵심 원칙

핵심은 “사용자는 방금 본 페이지로 다시 돌아올 수 있다.” 라는 사용자 경험(UX) 기반의 원칙입니다.

동작 방식

데이터를 사용하는 컴포넌트가 화면에서 사라지거나 (언마운트), 더 이상 해당 데이터를 사용하지 않게 되어 안 쓰는 데이터가 되었을 경우, 설정된 gcTime (기본값은 5분) 동안은 캐시에서 즉시 삭제하지 않고 임시로 보관합니다. 이 시간 동안 사용자가 다시 해당 데이터를 요청하면, 네트워크 로딩 없이 캐시된 데이터를 즉시 보여줄 수 있습니다. gcTime이 지나면 해당 캐시는 가비지 컬렉션의 대상이 되어 메모리에서 완전히 제거됩니다.

실사용 예시

상품 목록 페이지를 예로 들 수 있습니다. 목록(A)에서 특정 상품의 상세 페이지(B)로 이동했다가 ‘뒤로 가기’를 통해 다시 목록(A)으로 돌아왔을 때, gcTime 덕분에 목록(A)이 로딩 화면 없이 즉시 화면에 뜨게 됩니다. 이때 화면에 보이는 데이터는 캐시된 데이터이지만, 배경에서는 최신 정보로 업데이트하는 작업이 동시에 진행되어 사용자에게 빠른 응답성과 최신 정보를 모두 제공할 수 있습니다.

---

참고

Practical React Query | TkDodo’s blog