TanStack Query - staleTime과 gcTime 차이점 정리

Hushed_Mind·2025년 3월 30일

react-query 캐시 프론트엔드

React

목록 보기

2/7

TanStack Query (구 React Query)에서 staleTime과 gcTime은
데이터의 신선도와 생존 시간을 조절하는 중요한 캐싱 전략 설정이다.

staleTime 이란?

데이터가 '신선(fresh)'한 상태로 간주되는 시간을 의미.

동작 방식

데이터를 fetch한 시점부터 staleTime이 지나기 전까지는 신선한 상태로 간주
refetch 조건이 만족되더라도 네트워크 요청이 발생하지 않고 캐시된 데이터 사용
staleTime이 지난 후에 refetch 조건이 만족되면 네트워크 요청이 발생

📎 기본값: 0ms (즉시 stale 처리됨)

staleTime 예제

import { useQuery } from '@tanstack/react-query';
import axios from 'axios';

function Profile() {
  const { data, isLoading } = useQuery({
    queryKey: ['user'],
    queryFn: () => axios.get('/api/user').then(res => res.data),
    staleTime: 1000 * 60 * 5, // 5분
  });

  if (isLoading) return <p>Loading...</p>;

  return <div>{data.name}</div>;
}

이 경우, 데이터를 가져온 5분 이내에는 refetch가 트리거되더라도 캐시 데이터만 사용하고, 네트워크 요청은 발생하지 않는다.

gcTime 이란?

쿼리를 사용하는 컴포넌트가 언마운트되고 나서 캐시를 유지할 시간

동작 방식

컴포넌트가 언마운트되면 해당 쿼리는 더 이상 사용되지 않음
이때부터 gcTime 타이머가 시작되고, 시간이 지나면 캐시가 삭제됨
gcTime 이전에는 다시 마운트되면 기존 캐시를 재사용함
이후에는 다시 네트워크 요청이 발생

📎 기본값: 1000 * 60 * 5(5분)

gcTime 예제

import {useQuery} from "@tanstack/react-query";
import axios from "axios";

const TodoList = () => {
    const {data} = useQuery({
        queryKey: ['todos'],
        queryFn: () => axios.get('/api/todos').then((res) => res.data),
        staleTime: 0,
        gcTime: 1000 * 60 * 10, // 10분 동안 유지
    });

    return (
        <ul>
            {data?.map(todo => {
                <li key={todo.id}>{todo.title}</li>
            })}
        </ul>
    )
}

이 경우에는

데이터는 fetch 후 즉시 stale 상태가 되므로, 다시 마운트될 때마다 refetch 가능성 있음.
하지만 컴포넌트가 언마운트되고 10분 이내에 다시 마운트되면, 기존 캐시가 그대로 사용됨.
10분이 지나면 캐시가 삭제되고, 네트워크 요청이 발생

staleTime vs gcTime 정리

구분	설명	기본 값	예시
staleTime	캐시된 데이터를 신선하다고 간주 하는 시간	0ms	refetch가 발생해도 요 청 안보냄
gcTime	쿼리가 사용되지 않은 후 캐시를 유지하는 시간	5분	해당 쿼리 사용 X 상태에서 유지 시간