Synchronize Stale time

[acraftydev]

I have a number of api endpoints that show data but could be viewed from various screens and the stale time whilst set to the same value will be based on when they open the screen eg

/api/invoice-summary
/api/invoices
/api/inoivce/1/

The issue i have is the stale time will expire differently dependng when the queries are triggered which means they can get out of synch, where i would prefer there are synced so that i have some confiendence they are showing similar values. is that possible?

thanks

[ado11231]

Instead of a countdown, use clock alignment, make all queries expire at the same fixed points in time, TanStack v5 lets staleTime accept a function that returns a number. You calculate "how many milliseconds until the next 5-minute mark" and return that. Every query, no matter when it loads, will go stale at the same clock boundary.

function alignedStaleTime(intervalMs) {
  return () => {
    const now = Date.now();
    const nextBoundary = Math.ceil(now / intervalMs) * intervalMs;
    return nextBoundary - now;
  };
}

Apply the same function to all related queries and they'll always expire together.

[devangpratap]

staleTime starts counting from when each query's data was last fetched. If the queries fire at different times, they'll naturally drift out of sync. There's no built-in way to align their timers.

The simplest fix is to structure your keys with a shared prefix and invalidate them together.

useQuery({ queryKey: ['invoices', 'summary'], queryFn: fetchSummary })
useQuery({ queryKey: ['invoices', 'list'], queryFn: fetchInvoices })
useQuery({ queryKey: ['invoices', 'detail', id], queryFn: () => fetchInvoice(id) })

Then after any mutation that touches invoice data:

queryClient.invalidateQueries({ queryKey: ['invoices'] })

This forces every query under the ['invoices'] prefix to refetch at the same time, so they stay consistent.

If you're polling instead of doing mutation-based invalidation, set the same refetchInterval on each query. They'll drift slightly based on mount time but it keeps them close enough for most cases.

[aymenhmaidiwastaken]

The issue is that staleTime starts counting from when each query's data was last fetched. If queries fire at different times, they'll naturally drift apart.

Solution — Use a staleTime function to align all queries to the same clock:

TanStack Query v5 lets staleTime accept a function. You can align all queries to expire at the same fixed intervals (e.g., every 5 minutes on the clock):

const INTERVAL = 5 * 60 * 1000; // 5 minutes

const alignedStaleTime = () => {
  const now = Date.now();
  const nextTick = Math.ceil(now / INTERVAL) * INTERVAL;
  return nextTick - now;
};

// Use the same function for all related queries
useQuery({
  queryKey: ['invoice-summary'],
  queryFn: fetchInvoiceSummary,
  staleTime: alignedStaleTime,
});

useQuery({
  queryKey: ['invoices'],
  queryFn: fetchInvoices,
  staleTime: alignedStaleTime,
});

This way, all queries become stale at the same wall-clock moment, regardless of when they were individually fetched. They'll all refetch together on the next window focus or interval.

Alternative — Use a shared queryKey prefix and invalidate together:

// Invalidate all invoice-related queries at once
queryClient.invalidateQueries({ queryKey: ['invoice'] });

This forces all queries with a matching prefix to refetch simultaneously, which guarantees they show consistent data.

[acraftydev]

Thanks for the advice going to try the function for stale time.

…

On Mon, 25 May 2026, 15:09 Aymen Hmaidi, ***@***.***> wrote: The issue is that staleTime starts counting from when each query's data was last fetched. If queries fire at different times, they'll naturally drift apart. *Solution — Use a staleTime function to align all queries to the same clock:* TanStack Query v5 lets staleTime accept a function. You can align all queries to expire at the same fixed intervals (e.g., every 5 minutes on the clock): const INTERVAL = 5 * 60 * 1000; // 5 minutes const alignedStaleTime = () => { const now = Date.now(); const nextTick = Math.ceil(now / INTERVAL) * INTERVAL; return nextTick - now;}; // Use the same function for all related queriesuseQuery({ queryKey: ['invoice-summary'], queryFn: fetchInvoiceSummary, staleTime: alignedStaleTime,}); useQuery({ queryKey: ['invoices'], queryFn: fetchInvoices, staleTime: alignedStaleTime,}); This way, all queries become stale at the same wall-clock moment, regardless of when they were individually fetched. They'll all refetch together on the next window focus or interval. *Alternative — Use a shared queryKey prefix and invalidate together:* // Invalidate all invoice-related queries at oncequeryClient.invalidateQueries({ queryKey: ['invoice'] }); This forces all queries with a matching prefix to refetch simultaneously, which guarantees they show consistent data. — Reply to this email directly, view it on GitHub <#10726 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AACOS7X5UIOHTB4LNOB5HF344RHYPAVCNFSM6AAAAACZC5UKXSVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTOMBVGA4TONQ> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>. You are receiving this because you authored the thread.Message ID: ***@***.***>

[DaCameraGirl]

The core issue here is that each query's staleTime countdown starts from when that specific query was last fetched — so queries fetched at different times naturally expire at different times, even if they all have the same staleTime duration.

There are a few approaches to solve this depending on what "synchronized" means to you.

Option 1: Aligned staleTime (Clock-Based Expiry)

Instead of a fixed duration, use a function for staleTime that calculates the remaining milliseconds until the next fixed boundary. This means all queries expire at the same wall-clock moment regardless of when they were fetched:

const SYNC_INTERVAL_MS = 5 * 60 * 1000 // 5 minutes

// Returns ms until the next 5-minute boundary from epoch
const alignedStaleTime = () => {
  const now = Date.now()
  const nextBoundary = Math.ceil(now / SYNC_INTERVAL_MS) * SYNC_INTERVAL_MS
  return nextBoundary - now
}

// Apply to all related queries
useQuery({
  queryKey: ['invoice-summary'],
  queryFn: fetchInvoiceSummary,
  staleTime: alignedStaleTime, // TanStack Query v5 accepts a function
})

useQuery({
  queryKey: ['invoices'],
  queryFn: fetchInvoices,
  staleTime: alignedStaleTime,
})

useQuery({
  queryKey: ['invoice', id],
  queryFn: () => fetchInvoice(id),
  staleTime: alignedStaleTime,
})

All three will become stale at the same 5-minute clock tick, regardless of when they were each individually loaded.

Note: The staleTime function form was introduced in TanStack Query v5. In v4, you'd compute it as a value at call time instead.

Option 2: Shared refetchInterval with Polling

If you want them to actively refresh together (not just expire together), use a shared polling interval anchored to a fixed clock:

const POLL_INTERVAL_MS = 5 * 60 * 1000

// Compute the delay until the next boundary (same as above)
const msUntilNextTick = () => {
  const now = Date.now()
  return Math.ceil(now / POLL_INTERVAL_MS) * POLL_INTERVAL_MS - now
}

// On app init or a shared timer, invalidate all at once
useEffect(() => {
  const scheduleNextInvalidation = () => {
    const delay = msUntilNextTick()
    const timer = setTimeout(() => {
      queryClient.invalidateQueries({ queryKey: ['invoices'] }) // prefix match
      scheduleNextInvalidation() // re-schedule for next interval
    }, delay)
    return timer
  }

  const timer = scheduleNextInvalidation()
  return () => clearTimeout(timer)
}, [queryClient])

This approach uses queryClient.invalidateQueries with a key prefix to invalidate all invoice-related queries simultaneously on a clock boundary.

Option 3: invalidateQueries with a Shared Prefix Key

If you want to keep it simple and trigger re-fetches manually (e.g., when a user navigates to a screen or takes an action):

// All invoice queries share the 'invoices' prefix in their queryKey
useQuery({ queryKey: ['invoices', 'summary'], ... })
useQuery({ queryKey: ['invoices', 'list'], ... })
useQuery({ queryKey: ['invoices', 'detail', id], ... })

// Invalidate all at once with one call
queryClient.invalidateQueries({ queryKey: ['invoices'] })

This doesn't synchronize stale time automatically but gives you a single control point to trigger coordinated refetches.

Recommendation

Goal	Best approach
Stale at the same wall-clock time	Option 1: alignedStaleTime function
Active refresh at the same moment	Option 2: Scheduled invalidateQueries
Manual coordinated refresh trigger	Option 3: Shared prefix + invalidateQueries

Option 1 is the most elegant for your use case — it's purely declarative, requires no side effects or timers, and ensures all queries become stale at the same fixed interval boundaries no matter when they were last fetched.