Learning TanStack Query - Staleness & Refetching

#Introduction

One of TanStack Query's most noticeable features in real applications is automatic refetch: data is refreshed in the background without you writing a single line. But automatic doesn't mean uncontrollable — precisely because there are many triggers, you need to know which one to press and when.

Episode 7 unpacks the two timers that are most often confused (staleTime and gcTime), then all the automatic and manual refetch mechanisms available.

#Fresh vs Stale

#The Concept of Freshness

Data in TanStack Query lives in two conditions: fresh and stale. Fresh data is considered new enough to use without refetching. Stale data is considered updatable and will be refetched when there is a trigger. The boundary between the two is determined by staleTime:

Setting staleTime

useQuery({
  queryKey: ["todos"],
  queryFn: fetchTodos,
  staleTime: 30 * 1000,
})

staleTime: 30 * 1000 means the data is considered fresh for 30 seconds after the fetch completes. After that the data becomes stale, and any refetch trigger will grab the latest version. staleTime is counted from the last time data was successfully fetched.

#staleTime vs gcTime

These two timers are often confused. The core difference:

staleTime → when data is considered stale (still in cache, ready to refetch)
gcTime    → when the cache is evicted from memory (data gone, refetch)

The summary staleTime → when data is considered stale emphasizes that stale data is still available in the cache and displayed immediately, it just is considered in need of a refresh. gcTime, which runs when there are no observers, removes the data entirely from memory — completely different from merely marking it stale.

#Automatic Refetch

#refetchOnWindowFocus

When the user returns to the browser tab, TanStack Query refetches all stale queries by default. This keeps the application fresh after the user has been away:

Refetch on window focus

useQuery({
  queryKey: ["todos"],
  queryFn: fetchTodos,
  refetchOnWindowFocus: true,
})

Active by default. Set it to false if your application prefers full control, or configure it on the global QueryClient as in episode 3.

#refetchOnReconnect

When the network connection returns after being disconnected, stale queries are refetched automatically. This feature is important for mobile applications and environments with unstable connections:

Refetch on reconnect

refetchOnReconnect: true,

#refetchInterval: Polling

For data that keeps changing — prices, job status, match scores — use polling with refetchInterval:

Polling every 5 seconds

const { data } = useQuery({
  queryKey: ["job-status"],
  queryFn: fetchJobStatus,
  refetchInterval: 5000,
})

refetchInterval: 5000 refetches every 5 seconds as long as there is an active observer. refetchIntervalInBackground can be added to poll even when the tab isn't focused, but make sure you don't overload the server.

#Manual Refetch

#The refetch Method

Sometimes automatic triggers aren't enough — for example a "Reload" button pressed by the user. useQuery returns the refetch method:

Manual refetch

function Todos() {
  const { data, refetch, isFetching } = useQuery({
    queryKey: ["todos"],
    queryFn: fetchTodos,
  })
 
  return (
    <div>
      <button onClick={() => refetch()} disabled={isFetching}>
        Muat Ulang
      </button>
      <ul>{data?.map((todo) => <li key={todo.id}>{todo.title}</li>)}</ul>
    </div>
  )
}

refetch() forces a new data fetch, and isFetching indicates whether a fetch is currently running. Note that refetch only fetches data if the query is stale unless forced — TanStack Query handles the details of this behavior automatically.

#Combining All Triggers

Remember when each trigger works:

component mount (stale query) → refetch
window focus returns         → refetchOnWindowFocus
network reconnects            → refetchOnReconnect
polling interval              → refetchInterval
button / event                → manual refetch()

The summary component mount (stale query) → refetch shows the most common case: a component mounts and its data is already stale, so the query is refetched. The other triggers are just variations on the same principle.

#Closing

Episode 7 gave you full control over when and how data is refreshed. You understand the difference between staleTime and gcTime, automatic triggers like window focus and reconnect, polling with refetchInterval, and manual refetch.

Key takeaways:

• staleTime determines when data is considered stale; gcTime determines when the cache is evicted.
• Stale data remains available in the cache and is displayed immediately.
• refetchOnWindowFocus and refetchOnReconnect are active by default.
• refetchInterval for polling data that changes often.
• The refetch() method for manual triggers from user events.
• Refetch triggers only work on stale queries.

In the next episode, episode 8, we will discuss dependent and parallel queries — fetching several queries at once with useQueries, and queries that wait for another query's result with the enabled option. These are important patterns for dashboard pages and interdependent data.