updateTag vs revalidateTag

[mblandr]

Don't understand real difference of these both?
revalidateTag mark invalidate data cache entries for given tag and fully rerenders current route in browser.
updateTag mark invalidate data cache entries for given tag, refetch invalidated data for current route in browser and rerender full route.
So what is real difference, since in all case currrent route fully rerenders, so invalidated by tag data with both case refreshes while renders?
For invalidated data in other routes both only mark them as invalid.
Thanks in advance!

[icyJoseph]

revalidateTag is now, more in line with stale-while-revalidate, meaning that stale data is served, while it is revalidated in the "background".

updateTag is more of a read-your-write handler. It'll mark the data as expired, forcing any new data fetches to block until the data resolves.

• https://nextjs.org/docs/beta/app/api-reference/functions/updateTag#differences-from-revalidatetag

[mblandr]

I should mention that documentation is often far from ideal. Especially now, when we have many changes in behavior.
Of course, I read this, but I didn't found any difference in practice, but I will check again.
Next question - we have now two different caching API - 1)fetch on pair with unstable_cache
2)'use cache'
are revalidateTag and updateTag have equal behavior for both strategies or new behavior only for new 'use cache'?
And why do we have updateTag but not updatePath with similar changes compare to revalidatePath?

[icyJoseph]

Could you sum up what's not adding up for you in the difference?

• revalidateTag - stale while revalidate behavior,
• updateTag - blocking revalidate on next visit,

Also updateTag can only be called in a server action.

updateTag immediately expires the cached data for the specified tag, causing the next request to that resource to be a blocking revalidate/cache miss. This ensures that Server Actions can immediately see their own writes.

unstable_cache - as documented here, https://nextjs.org/docs/app/api-reference/functions/unstable_cache - will be replaced by use cache.

There's cacheTag to tag usage of use cache, and revalidate/update these, separately from the cacheLife profile.

As for the last question, reading the PR that introduced this change, I guess, it might become a thing later on. No promises though, I haven't asked around, but a comment on the PR makes me suspect that it has at least been considered.

[mblandr]

No, I mean: - right now unstable_cache and fetch cache exist in next.js, so
1)is updateTag apply to unstable_cache and fetch with cache?
2)has revalidateTag for unstable_cache and fetch with cache old semantic, or new semantic?

And I something misunderstood yet, sorry.
if tag revalidated, next time when it is read, it revalidatates in background right in place as SWR. What mean has additional cache profile in revalidateTag, if data always refresh right in place?

Maybe I misunderstood cacheLife semantic, so here how I understand it.

route segments- layout, page - use cacheLife for configure cache profile for router cache and full route cache.
stale - time to live segment in RC,
revalidate - mininum of all revelidate in all segments is a time to live in FRC whole route,
if some segment don't have use cache or cachelife - it does't include in calculation
but what is expire - according to docs: "Maximum duration for which a value can remain stale before switching to dynamic fetching" - i think and practice test shows that it doesn't make any sense and don't apply to render function.
I think expire doesn't apply to render function.

for other function -
stale - don't have any sense
revalidate - time to be actual in DataCache without background refreshing, after that interval - SWR
expire - time to be valid in DataCache, after that interval read value awaits for update is finished - like updateTag.
Where am I wrong?

[icyJoseph]

1)is updateTag apply to unstable_cache and fetch with cache?

AFAIK, yes, but moving forward, the idea is to use use cache instead of unstable_cache

2)has revalidateTag for unstable_cache and fetch with cache old semantic, or new semantic?

Err, I am not sure I understand, but the function behaves as described, regardless of the implementation detail - in other words, the function interacts with the cache, rather than with the mechanism to store things in the cache.

As far as I know:

• stale: NOT used for data cache - this is primarily for client-side Router Cache duration
• revalidate: Time until the entry becomes stale and triggers background revalidation (SWR semantics)
• expire: Maximum lifetime of cached entry. After this, the entry is completely invalid and requires blocking revalidation

What mean has additional cache profile in revalidateTag, if data always refresh right in place?

The profile's expire time is the window of time that stale data is allowed to be served. One that voids, one should block until fresh data is available. If the data finishes refresh between two calls, the second call is now seeing fresh data, and the first call got non-blocking stale data. If the expire time had voided after the first call, and the refresh did not finish, the second call would wait for that to complete.

What do you mean here? I think expire doesn't apply to render function.

[DanielSalazarLoaiza]

Both revalidateTag() and updateTag() invalidate cache entries for the given tag, but the key difference is when the data refetch happens.

revalidateTag(tag) only marks the data as stale — the refetch and rerender happen on the next navigation or refresh.

updateTag(tag) immediately triggers a client-side refetch of all data using that tag and rerenders the current route right away.

So:

revalidateTag = “invalidate now, update later.”

updateTag = “invalidate and update now.”

[mblandr]

Sorry for pause, I learned some alternatives like Sveltekit, Nuxt, Asto. Most interesting is Sveltekit. of course, I peronally think that its philosophy far better then Next, but it misses some key features. But this is offtop, I only shuld say KEY thing - documentation of sveltekit is WAY better then next.js, in my opinion.
So back to discussion
I try to formulate as I understood,
About invalidate
If invalidate has second argument - profile - then it uses SWR semantic and uses its {revalidate, expire} parts. So we can say that invalidate with second argument actually sets a new cache profile for this entry and mark data as "touched" (or "readed") (so interval starts to count from this moment)?

I think expire doesn't apply to render function.
I mean cacheLife applies to any async function, includes react component function. But there is a huge difference - usual function cached in Data cache, component function - in Full Route Cache and Router Cache, right?
So I think that for usual functions make sense only {expire, revalidate} parts, because {stale} - for Router Cache, and function results don't cache in Router Cache.
But for react component functions make sense only {stale, revalidate}:
minimum of all state in all rscp fragments in Router cache defines interval to store rscp fragment in Router Cache
minimum of all revalidate all route RSC components defines interval rerender in Full Route Cache
And there is no meaning for {expire} key in cache profile in case of react component functions. Otherwise what means {expire} in cache profile for REACT COMPONENT function, not usual function?

And while discussion continues, Next 16 is out. cacheComponent is now stable.
And here what I mean about problems with next documentation.
https://nextjs.org/docs/app/getting-started/cache-components
"With Cache Components enabled, Next.js treats all routes as dynamic by default."
It is totally wrong. As usually, by default all routes is static.
Next:
"Dynamic data patterns include:
fetch requests
Database queries
connection"

What is happened with draftMode? It still exists, but not mentioned
What is exact database query?
"fetch" - of course, it means uncached fetch, i.e.
method get with cache: 'no-store' or next.revalidate: 0
or method not get? Or may be cache extension of fetch functionality by react/next is no more exists in cacheComponents mode?

Some experiments show that cacheComponents works like this:
any route is as usually treated as static by default.
but when route component await non-trivial promise that not cached by any next.js caching methods for fetch of function with revalidate interval > 0 (trivial promise - it is a promise resolving right now, without any async operaiton), it generates conflict with static nature of route and should wrapped in Suspense with static fallback or throw error in render.

So I can use db queries and it will NOT be a dynamic data - for example, there exists sync API for SQLite, and it will not treats as dynamic data.
And I can do just this in RSC:
await new Promise((resolve) => setTimeout(resolve, 1000));
this is not dynamic data in sense mentioned in documentation, BUT it generates error Uncached data was accessed outside of Suspense

That is what I don't like in any documentation - when don't describe logic how it really works, but use some general words with uncertain underground context.
So I ask nex js team be more accurate in documentation, please.

Next:
expriments show, that in cached function
cacheLife('hours') works
but cacheLife({ stale: 5, expire: 20, revalidate: 10 }) don't - I got error "Uncached data was accessed outside of Suspense".
Is it a bug?
Thanks in advance, see you next

[mblandr]

And another inconstancy in documentation:
https://nextjs.org/docs/app/api-reference/directives/use-cache
"The use cache directive allows you to mark a route, React component, or a function as cacheable"
"The return value of the cacheable function must be serializable"

https://react.dev/reference/rsc/use-server#serializable-parameters-and-return-values
"Notably, these are not supported:
React elements, or JSX"

So, how can we mark react component as cacheable, when it is a function that returns react elements, which are not serializable?

[icyJoseph]

"With Cache Components enabled, Next.js treats all routes as dynamic by default."

What happens here is that PPR walks your route collecting static parts of the page, and dynamic data that is use cache'd, to render a static shell. When it encounters runtime or dynamic data it renders the fallback UI of the suspense boundary wrapping this section, and it also adds it to the static shell.

When a request arrives, it can serve the static shell, and then whatever runtime/dynamic data you had, is sent to the client.

It is a change on how pages are rendered.

What is exact database query? and fetch

Previously, the stable APIs allow you to opt-in into caching with fetch. However, that's not the only way to get data. Some might use their own client, built on top of the HTTP Node.js module, or file system, etc... further more, configuring fetch was overhead. You can still use it in Cache Components, but you don't have to.

Now you can use put use cache where you do your transaction, none of the above matters, cacheTag it, or add a cacheLife, and continue.

This is good feedback though. I'll make more adjustments to the cache components API reference.

cacheLife({ stale: 5, expire: 20, revalidate: 10 }) don't - I got error "Uncached data was accessed outside of Suspense".

I think the https://nextjs.org/docs/messages/blocking-route#short-lived-caches error page is what you are looking for ~ already asked the team internally to maybe link to that section of the docs, in this case, if possible.

[icyJoseph]

Regarding the serialization that's because React's serialization is used (which can handle bigint and other stuff for example), and they make a distinction for arguments, and return types, from - https://react.dev/reference/rsc/use-server#serializable-parameters-and-return-values:

Supported serializable return values are the same as serializable props for a boundary Client Component.

And https://react.dev/reference/rsc/use-client#serializable-types says:

Serializable types returned by Server Components

• Client or Server Component elements (JSX)

Mmm I'll update some of our links, but I can understand the confusion.

And yes, server actions can return components too.

[mblandr]

O, ya, about serializable value - it is my mistake. It was serializable values returned from Server Functions, not RSC, as you points to me. Thanks

[mblandr]

Hmm. comparing two lists
https://react.dev/reference/rsc/use-client#serializable-types
https://react.dev/reference/rsc/use-server#serializable-parameters-and-return-values
I see that FormData CAN be passed to Server Function but CAN"T RETURNED from - it is not in list:
"Supported serializable return values are the same as serializable props for a boundary Client Component."
but I check - I CAN return FormData from Server Function into browser and CAN pass to client from RSC.

So react docs needs some changes
https://react.dev/reference/rsc/use-client#serializable-types - in this list should insert FormData

[mblandr]

Ok, but
cacheLife({ stale: 100, expire: 3000, revalidate: 2000 });
make error TOO.
Is it short-lived caches too?

[icyJoseph]

Screenshot of error?

[mblandr]

my bad, it works, now this point clear, thanks again

[icyJoseph]

No worries. We have to land this correctly. Landing a feature goes beyond the date of shipping, it is also how we teach and document it over time. These kind of conversations are invaluable.

[mblandr]

No-no, how ppr works I understood, documentation is clear at this point. but I think
"With Cache Components enabled, Next.js treats all routes as dynamic by default" needs correction.

[icyJoseph]

Cache components extracts the static content - if its 100% static, then it can serve that immediately.

[mblandr]

More important point, I should understand, how much am I wrong in this key points:
1)
I mean cacheLife applies to any async function, includes react component function. But there is a huge difference - usual function cached in Data cache, component function - in Full Route Cache and Router Cache, right?
So I think that for usual functions make sense only {expire, revalidate} parts, because {stale} - for Router Cache, and function results don't cache in Router Cache.
But for react component functions make sense only {stale, revalidate}:
minimum of all state in all rscp fragments in Router cache defines interval to store rscp fragment in Router Cache
minimum of all revalidate all route RSC components defines interval rerender in Full Route Cache
And there is no meaning for {expire} key in cache profile in case of react component functions. Otherwise what means {expire} in cache profile for REACT COMPONENT function, not usual function?

[icyJoseph]

Mmm I am having a hard time following here

The expire key is the time after which, you'd block to generate a response. If you are still within revalidate, a stale output is used and a new one is generated in the background. If you exceeded the revalidate time, the next request blocks to collect new output.

[mblandr]

I understood this, but I was wrong about expire - I make conclusion that expire applies and for react component function too. Thanks

[mblandr]

Are other points correct? this:

minimum of all stale in all rscp fragments in Router cache defines interval to store rscp fragment in Router Cache
minimum of all revalidate and minimum of all expire of all route's RSC components defines rerender intervals and behavior for whole route in Full Route Cache

[icyJoseph]

I am not sure about the revalidate - I'll touch base on Monday I have to leave for now

[mblandr]

Thanks again

[mblandr]

Because in my opinion documentation about cacheLife profile very uncertain about core cache logic

[mblandr]

2. when route component await non-trivial promise that not cached by any next.js caching methods for fetch of function with revalidate interval > 0 (trivial promise - it is a promise resolving right now, without any async operaiton), it generates conflict with static nature of route and should wrapped in Suspense with static fallback or throw error in render.

[icyJoseph]

any route is as usually treated as static by default.

Cache components extracts the static content - if its 100% static, then it can serve that immediately

Interesting, observable behavior vs implementation detail at play here, I'll review this and how to communicate it better in the API reference.

[mblandr]

thanks, i will wait you resume