React Query Cache: staleTime vs cacheTime Explained

Problem: Caching API Data with Time-Based Control

When working with React Query for data fetching, many developers struggle to understand the difference between staleTime and cacheTime. You might want to store API data for a specific duration (like 2 minutes) and prevent unnecessary API calls during that period, regardless of component mounting/unmounting.

The confusion often arises when:

• Using only staleTime doesn't trigger API refreshes when expected
• Using only cacheTime causes API calls to happen more frequently than desired

Solution: Understanding the Distinct Roles

Here's the key distinction: staleTime controls data freshness while cacheTime controls garbage collection.

staleTime: Your Data Freshness Guarantee

const query = useQuery(
  ["getUserList"], 
  getUserList, 
  {
    staleTime: 120000, // Data stays fresh for 2 minutes
  }
);

staleTime specifies how long your data is considered "fresh" after a successful fetch. While data is fresh:

• No background refetches will occur
• Data is served instantly from cache
• It works similarly to Cache-Control: max-age=120 in HTTP caching

cacheTime: Memory Management for Unused Data

const query = useQuery(
  ["getUserList"], 
  getUserList, 
  {
    cacheTime: 120000, // Unused data persists for 2 minutes
  }
);

cacheTime determines how long unused query data remains in memory before being garbage collected. This only applies when:

• No components are actively using the query (all observers have unmounted)
• The data is no longer being displayed or referenced

Default Values

• staleTime: 0 (data becomes stale immediately)
• cacheTime: 300000 (5 minutes)

Practical Implementation

For your specific requirement of caching data for 2 minutes:

const query = useQuery(
  ["getUserList"], 
  getUserList, 
  {
    staleTime: 120000,    // Data remains fresh for 2 minutes
    cacheTime: 300000,    // Keep unused data for 5 minutes (default)
  }
);

This configuration ensures:

• No API calls for 2 minutes after successful data fetch
• Data persists in cache even if component unmounts
• Automatic refetch after staleTime expires when component remounts

How React Query Processes Queries

Step-by-Step Data Flow

Common Misconceptions and Solutions

Don't Confuse staleTime with Refetch Interval

If you want to automatically refetch every 2 minutes regardless of component state, use refetchInterval instead:

const query = useQuery(
  ["getUserList"], 
  getUserList, 
  {
    refetchInterval: 120000, // Refetch every 2 minutes
  }
);

CacheTime Doesn't Prevent Refetches

cacheTime only affects garbage collection of unused queries. Active queries will still follow staleTime rules for refetching behavior.

Best Practices

1. Set appropriate staleTimes based on your data volatility:

   • Real-time data: staleTime: 0
   • User data: staleTime: 5 * 60 * 1000 (5 minutes)
   • Static content: staleTime: Infinity

2. Keep cacheTime longer than staleTime to allow returning to previously visited views without refetching

3. Use descriptive query keys to ensure proper cache identification

4. Consider your user experience - balance between freshness and performance

By understanding these fundamental concepts, you can effectively control your application's caching behavior and optimize both performance and data freshness.