staleTimes vs stale option in cache profile

[mblandr]

Don't understand, why in experimental.staleTimes i can differentiate static and dynamic individually,
but in cache profile I have only one stale?. Does it mean that stale option define both static and dynamic part? Ore I miss something?
Thanks

[icyJoseph]

Let's see, the time has come to start answering questions about these APIs.

With the stale option in your cacheLife profile, you can inform the client side router (rather the framework does that for you), that when this page was made, a cached function that'll eventually go stale, was used. This time is shared by the server with the client. So the client should revalidate this page after that time.

This effectively means, that the static/dynamic distinction is not necessary in your mental model. If I stop here, does that answer your question?

[mblandr]

Docs is very unclear.
So I will explain situation as I understood by points
1)we have Router cache, it holds RSCP for page, layout and Suspense fallback
2)we can control duration while RSCP for page is in this cache without refreshing RSCR from server
3)not for back/forward navigation, it uses cached RSCP for page no matter expire or not
4)not for layout, it uses RSCP for layout no matter expire or not
5)not for suspense fallback
6)we have default time for duration when RSCP for given page lives in this cache for client-side navigation (not back/forward) without re-fetch RSCP from server for page
7)there are two different duration for different condition, named dynamic and static
8)this options controlled by experimental.staleTimes with TWO distinct value
For this moment, are every points correct?

Now we take in account use cache directive
8)it use cache profile, predefined or customized, no matter
9)profile have option stale with ONE value
So what this stale mean?
Time to live RSCP for page in router cache? Then it should be TWO different options
Something else? But time to live WHAT and in WHERE?
On client we have only Router Cache with RSCP with behavior described above
So we have another type of cache or not? If yes, why it isn't described in docs
If no, why do we have conflict - one or two config options?

[icyJoseph]

Right, first thing would be point out that these are experimental configurations, closer, but yet not stable.

8. it use cache profile, predefined or customized, no matter
9. profile have option stale with ONE value
   So what this stale mean?

The key insight is that the stale option in cacheLife profiles inherits from and can override the staleTimes configuration.
When using the default profile, it uses staleTimes.static as mentioned in the cacheLife docs, https://nextjs.org/docs/app/api-reference/functions/cacheLife#default-cache-profiles:

Good to know: Updating the staleTimes and expireTime config options also updates the stale and expire properties of the default cache profile.

And in the table in that link, you'll see the default stale is 5 minutes (which comes from staleTimes.static).

So when you define your own profile's stale value, you're saying "this specific page/component should refresh at this interval instead of the default." It's a way to have page specific cache timing while still having sensible defaults.

So rather than thinking about cache layers, think of it as:

• staleTimes: Sets your app's default refresh intervals
• cacheLife({ stale: X }): Says "this specific function should refresh every X seconds instead"

And the last bit, as said in my previous comment:

With the stale option in your cacheLife({ stale: X }), you can inform the client side router (rather the framework does that for you), that when this page was made, a cached function that'll eventually go stale, was used. This time is shared by the server with the client. So the client should revalidate this page after that time.

This kind of discussion is important to contribute toward landing better documents.

[mblandr]

So we got KEY moments:
1.Router Cache can contains not only RSCP for layout, suspense and page BUT ALSO cache functions results.
2. RSCP cache has two options - static and dynamic, defined in experimental.staleTimes object, with some default values if not configured one/both of them.
3. function cache - only one option - stale, which is configured in cache profile via stale options
4. If we use profile (default or not) with NO customized stale value, it get stale value from experimental.staleTimes.static.
Like that?

[icyJoseph]

Yes, if you use no stale value in your profile (undefined), the static staleTime is used, though there's an edge case for the "seconds" profile, which uses dynamic. We should document this fallback behavior better.

• next.js/packages/next/src/server/config.ts

  Lines 946 to 957 in 531e938

  	const secondsCacheLifeProfile = result.experimental.cacheLife['seconds']
  	if (
  	secondsCacheLifeProfile &&
  	secondsCacheLifeProfile.stale === undefined
  	) {
  	// We default this to whatever stale time you had configured for dynamic content.
  	// Since this is basically a dynamic cache life profile.
  	const dynamicStaleTime = result.experimental.staleTimes?.dynamic
  	secondsCacheLifeProfile.stale =
  	dynamicStaleTime ?? defaultConfig.experimental?.staleTimes?.dynamic
  	}
  	}

I'd also like to clarify point 1 a bit more, the Router Cache contains RSC payloads for pages/layouts, not individual cache function results. When you use cacheLife() in functions, the client does not see those as individual data bits, rather, it sees the final rendered page response. AKA, the aggregated result.

The client gets from the server the minimum stale time from all your cache functions to determine when to refetch the entire page data from the server.

[mblandr]

O, thanks very match. It's like way better understandable now, so I think initial question was clarified.

[mblandr]

Still some strange happens.
I have this:
export const sample = async () => {
'use cache';
cacheLife({
stale: 20,
revalidate: 30,
expire: 40,
});
cacheTag('my_tag', 'my_tag1');
const res = await fetch('http://localhost:3001/api2');
const data = await res.text();
return data;
};

bun in fetch cache I got this:
{"kind":"FETCH","data":{"headers":{"content-length":"14","content-type":"text/plain;charset=utf-8","date":"Mon, 04 Aug 2025 15:57:12 GMT"},"body":"ISEhITY6NTY6NTggUE0=","status":200,"url":"http://localhost:3001/api2"},**"revalidate":900**,"tags":[]}
Why 900???? From where?
ok, change to
cacheLife('seconds');
still in fetch cache 900 seconds.
Why?

[icyJoseph]

how are you using this and how are you collecting the cache entry.

[icyJoseph]

Also, on which version are you on? And what experimental flags are active?