From 02c04f4d580b4117329ffa5fea542d3127bb072b Mon Sep 17 00:00:00 2001 From: Aurora Scharff Date: Sun, 5 Apr 2026 12:20:06 +0200 Subject: [PATCH 1/3] docs: link updateTag from cacheTag reference Add updateTag to related links and a Good to know bullet pointing to the updateTag API and Differences from revalidateTag, without duplicating examples. Made-with: Cursor --- docs/01-app/03-api-reference/04-functions/cacheTag.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/01-app/03-api-reference/04-functions/cacheTag.mdx b/docs/01-app/03-api-reference/04-functions/cacheTag.mdx index 5fdbf1105c142..bb2b545af1c21 100644 --- a/docs/01-app/03-api-reference/04-functions/cacheTag.mdx +++ b/docs/01-app/03-api-reference/04-functions/cacheTag.mdx @@ -8,6 +8,7 @@ related: - app/api-reference/config/next-config-js/cacheComponents - app/api-reference/directives/use-cache - app/api-reference/functions/revalidateTag + - app/api-reference/functions/updateTag - app/api-reference/functions/cacheLife --- @@ -85,6 +86,7 @@ export default async function submit() { ## Good to know +- **updateTag**: Call [`updateTag`](/docs/app/api-reference/functions/updateTag) from a [Server Action](/docs/app/getting-started/mutating-data) to expire the tag immediately so the next read fetches fresh data. Use this for **read-your-own-writes** after a mutation instead of the stale-while-revalidate flow shown above with [`revalidateTag`](/docs/app/api-reference/functions/revalidateTag). See [Differences from `revalidateTag`](/docs/app/api-reference/functions/updateTag#differences-from-revalidatetag). - **Idempotent Tags**: Applying the same tag multiple times has no additional effect. - **Multiple Tags**: You can assign multiple tags to a single cache entry by passing multiple string values to `cacheTag`. From 7495e84896d5dd9fe0bc3664e5fd030b5f2591e1 Mon Sep 17 00:00:00 2001 From: Aurora Scharff Date: Sun, 5 Apr 2026 12:33:34 +0200 Subject: [PATCH 2/3] docs: clarify updateTag invalidates cache entries, not the tag Made-with: Cursor --- docs/01-app/03-api-reference/04-functions/cacheTag.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/01-app/03-api-reference/04-functions/cacheTag.mdx b/docs/01-app/03-api-reference/04-functions/cacheTag.mdx index bb2b545af1c21..a40b56564ba4c 100644 --- a/docs/01-app/03-api-reference/04-functions/cacheTag.mdx +++ b/docs/01-app/03-api-reference/04-functions/cacheTag.mdx @@ -86,7 +86,7 @@ export default async function submit() { ## Good to know -- **updateTag**: Call [`updateTag`](/docs/app/api-reference/functions/updateTag) from a [Server Action](/docs/app/getting-started/mutating-data) to expire the tag immediately so the next read fetches fresh data. Use this for **read-your-own-writes** after a mutation instead of the stale-while-revalidate flow shown above with [`revalidateTag`](/docs/app/api-reference/functions/revalidateTag). See [Differences from `revalidateTag`](/docs/app/api-reference/functions/updateTag#differences-from-revalidatetag). +- **updateTag**: Call [`updateTag`](/docs/app/api-reference/functions/updateTag) from a [Server Action](/docs/app/getting-started/mutating-data) to expire the cached entries for this tag immediately so the next read fetches fresh data. Use this for **read-your-own-writes** after a mutation instead of the stale-while-revalidate flow shown above with [`revalidateTag`](/docs/app/api-reference/functions/revalidateTag). See [Differences from `revalidateTag`](/docs/app/api-reference/functions/updateTag#differences-from-revalidatetag). - **Idempotent Tags**: Applying the same tag multiple times has no additional effect. - **Multiple Tags**: You can assign multiple tags to a single cache entry by passing multiple string values to `cacheTag`. From ebb752d7a139d3197aa72cc9e76f14220900e89b Mon Sep 17 00:00:00 2001 From: Aurora Scharff Date: Tue, 7 Apr 2026 14:35:49 +0200 Subject: [PATCH 3/3] docs: move updateTag guidance to Usage section per review feedback Address review by presenting both invalidation APIs (updateTag and revalidateTag) upfront in the Usage section instead of only in a Good to know footnote. Made-with: Cursor --- docs/01-app/03-api-reference/04-functions/cacheTag.mdx | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/01-app/03-api-reference/04-functions/cacheTag.mdx b/docs/01-app/03-api-reference/04-functions/cacheTag.mdx index a40b56564ba4c..79af3ed3a2d02 100644 --- a/docs/01-app/03-api-reference/04-functions/cacheTag.mdx +++ b/docs/01-app/03-api-reference/04-functions/cacheTag.mdx @@ -60,7 +60,12 @@ export async function getData() { } ``` -You can then purge the cache on-demand using [`revalidateTag`](/docs/app/api-reference/functions/revalidateTag) API in another function, for example, a [route handler](/docs/app/api-reference/file-conventions/route) or [Server Action](/docs/app/getting-started/mutating-data): +You can then purge the cache on-demand from a [Server Action](/docs/app/getting-started/mutating-data) or [route handler](/docs/app/api-reference/file-conventions/route): + +- Use [`updateTag`](/docs/app/api-reference/functions/updateTag) inside a Server Action for immediate expiry so the next read fetches fresh data (read-your-own-writes). +- Use [`revalidateTag`](/docs/app/api-reference/functions/revalidateTag) when a stale-while-revalidate delay is acceptable, or when invalidating from a route handler. + +The example below uses `revalidateTag`: ```tsx filename="app/action.ts" switcher 'use server' @@ -86,7 +91,6 @@ export default async function submit() { ## Good to know -- **updateTag**: Call [`updateTag`](/docs/app/api-reference/functions/updateTag) from a [Server Action](/docs/app/getting-started/mutating-data) to expire the cached entries for this tag immediately so the next read fetches fresh data. Use this for **read-your-own-writes** after a mutation instead of the stale-while-revalidate flow shown above with [`revalidateTag`](/docs/app/api-reference/functions/revalidateTag). See [Differences from `revalidateTag`](/docs/app/api-reference/functions/updateTag#differences-from-revalidatetag). - **Idempotent Tags**: Applying the same tag multiple times has no additional effect. - **Multiple Tags**: You can assign multiple tags to a single cache entry by passing multiple string values to `cacheTag`.