From 08d57b5934f2c4803d2404b84237f33f969081a2 Mon Sep 17 00:00:00 2001 From: Joseph Chamochumbi Date: Tue, 29 Jul 2025 02:38:33 +0200 Subject: [PATCH 1/4] docs: Clarify revalidatePath - avoiding implementation details about caching --- .../03-api-reference/04-functions/revalidatePath.mdx | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/01-app/03-api-reference/04-functions/revalidatePath.mdx b/docs/01-app/03-api-reference/04-functions/revalidatePath.mdx index 6e559bb96ce0..03dfe2542425 100644 --- a/docs/01-app/03-api-reference/04-functions/revalidatePath.mdx +++ b/docs/01-app/03-api-reference/04-functions/revalidatePath.mdx @@ -5,11 +5,17 @@ description: API Reference for the revalidatePath function. `revalidatePath` allows you to purge [cached data](/docs/app/guides/caching) on-demand for a specific path. +## Usage + +`revalidatePath` can be called in Server Functions and Route Handlers. + +`revalidatePath` cannot be called in Client Components or Middleware, as it only works in server environments. + > **Good to know**: > -> - `revalidatePath` only invalidates the cache when the included path is next visited. This means calling `revalidatePath` with a dynamic route segment will not immediately trigger many revalidations at once. The invalidation only happens when the path is next visited. -> - Currently, `revalidatePath` invalidates all the routes in the [client-side Router Cache](/docs/app/guides/caching#client-side-router-cache) when used in a server action. This behavior is temporary and will be updated in the future to apply only to the specific path. -> - Using `revalidatePath` invalidates **only the specific path** in the [server-side Route Cache](/docs/app/guides/caching#full-route-cache). +> - **When revalidation happens**: `revalidatePath` schedules cache invalidation but doesn't immediately clear cached data. The actual revalidation is executed later in the request cycle. +> - **Navigation behavior**: When called in Server Functions, `revalidatePath` updates the UI (if the user is currently viewing the revalidated path) when the Server Function completes and causes data for all previously visited pages to refresh when navigated to again. This behavior is temporary and will be updated in the future to apply only to the specific path. +> - **Server-side behavior**: `revalidatePath` ensures that the specified path will be re-rendered with fresh data on subsequent visits, clearing both cached data and pre-rendered pages on the server. ## Parameters From 1ab46eb9af1d47f099837a9de224c71dcc0cc2b4 Mon Sep 17 00:00:00 2001 From: Joseph Chamochumbi Date: Tue, 29 Jul 2025 13:48:48 +0200 Subject: [PATCH 2/4] docs: reorganize good to know with usage context --- .../03-api-reference/04-functions/revalidatePath.mdx | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/01-app/03-api-reference/04-functions/revalidatePath.mdx b/docs/01-app/03-api-reference/04-functions/revalidatePath.mdx index 03dfe2542425..87c0fb889bdf 100644 --- a/docs/01-app/03-api-reference/04-functions/revalidatePath.mdx +++ b/docs/01-app/03-api-reference/04-functions/revalidatePath.mdx @@ -13,9 +13,8 @@ description: API Reference for the revalidatePath function. > **Good to know**: > -> - **When revalidation happens**: `revalidatePath` schedules cache invalidation but doesn't immediately clear cached data. The actual revalidation is executed later in the request cycle. -> - **Navigation behavior**: When called in Server Functions, `revalidatePath` updates the UI (if the user is currently viewing the revalidated path) when the Server Function completes and causes data for all previously visited pages to refresh when navigated to again. This behavior is temporary and will be updated in the future to apply only to the specific path. -> - **Server-side behavior**: `revalidatePath` ensures that the specified path will be re-rendered with fresh data on subsequent visits, clearing both cached data and pre-rendered pages on the server. +> - **Server Functions**: Updates the UI immediately (if viewing the revalidated path). Currently, it also causes all previously visited pages to refresh when navigated to again. This behavior is temporary and will be updated in the future to apply only to the specific path. +> - **Route Handlers**: Marks the path for revalidation. The revalidation is done on the next visit to the specified path. This means calling `revalidatePath` with a dynamic route segment will not immediately trigger many revalidation at once. The invalidation only happens when the path is next visited. ## Parameters @@ -73,7 +72,7 @@ revalidatePath('/', 'layout') This will purge the Client-side Router Cache, and revalidate the Data Cache on the next page visit. -### Server Action +### Server Function ```ts filename="app/actions.ts" switcher 'use server' From 189e8954b0ef4284d718fec90b2198eab6606a87 Mon Sep 17 00:00:00 2001 From: Joseph Chamochumbi Date: Tue, 29 Jul 2025 16:08:40 +0200 Subject: [PATCH 3/4] chore: pluralize revalidation process --- docs/01-app/03-api-reference/04-functions/revalidatePath.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/01-app/03-api-reference/04-functions/revalidatePath.mdx b/docs/01-app/03-api-reference/04-functions/revalidatePath.mdx index 87c0fb889bdf..4b3f4838057c 100644 --- a/docs/01-app/03-api-reference/04-functions/revalidatePath.mdx +++ b/docs/01-app/03-api-reference/04-functions/revalidatePath.mdx @@ -14,7 +14,7 @@ description: API Reference for the revalidatePath function. > **Good to know**: > > - **Server Functions**: Updates the UI immediately (if viewing the revalidated path). Currently, it also causes all previously visited pages to refresh when navigated to again. This behavior is temporary and will be updated in the future to apply only to the specific path. -> - **Route Handlers**: Marks the path for revalidation. The revalidation is done on the next visit to the specified path. This means calling `revalidatePath` with a dynamic route segment will not immediately trigger many revalidation at once. The invalidation only happens when the path is next visited. +> - **Route Handlers**: Marks the path for revalidation. The revalidation is done on the next visit to the specified path. This means calling `revalidatePath` with a dynamic route segment will not immediately trigger many revalidations at once. The invalidation only happens when the path is next visited. ## Parameters From 1565d54da5fffd77e3488d652e2457105b63dbb4 Mon Sep 17 00:00:00 2001 From: Joseph Chamochumbi Date: Wed, 30 Jul 2025 18:39:32 +0200 Subject: [PATCH 4/4] docs: Document revalidatePath and revalidateTag relationship --- .../04-functions/revalidatePath.mdx | 45 ++++++++++++++++++- .../04-functions/revalidateTag.mdx | 44 ++++++++++++++---- 2 files changed, 80 insertions(+), 9 deletions(-) diff --git a/docs/01-app/03-api-reference/04-functions/revalidatePath.mdx b/docs/01-app/03-api-reference/04-functions/revalidatePath.mdx index 4b3f4838057c..3ffab363f08a 100644 --- a/docs/01-app/03-api-reference/04-functions/revalidatePath.mdx +++ b/docs/01-app/03-api-reference/04-functions/revalidatePath.mdx @@ -22,13 +22,56 @@ description: API Reference for the revalidatePath function. revalidatePath(path: string, type?: 'page' | 'layout'): void; ``` -- `path`: Either a string representing the filesystem path associated with the data you want to revalidate (for example, `/product/[slug]/page`), or the literal route segment (for example, `/product/123`). Must be less than 1024 characters. This value is case-sensitive. +- `path`: Either a string representing the filesystem path associated with the data you want to revalidate (for example, `/product/[slug]/page`), or the literal route segment (for example, `/product/123`). Must not exceed 1024 characters. This value is case-sensitive. - `type`: (optional) `'page'` or `'layout'` string to change the type of path to revalidate. If `path` contains a dynamic segment (for example, `/product/[slug]/page`), this parameter is required. If path refers to the literal route segment, e.g., `/product/1` for a dynamic page (e.g., `/product/[slug]/page`), you should not provide `type`. ## Returns `revalidatePath` does not return a value. +## Relationship with `revalidateTag` + +`revalidatePath` and [`revalidateTag`](/docs/app/api-reference/functions/revalidateTag) serve different purposes: + +- **`revalidatePath`**: Revalidates a specific page or layout path +- **`revalidateTag`**: Revalidates data with specific tags across all pages that use those tags + +When you call `revalidatePath`, only the specified path gets fresh data on the next visit. Other pages that use the same data tags will continue to serve cached data until those specific tags are also revalidated: + +```tsx +// Page A: /blog +const posts = await fetch('/api/posts', { next: { tags: ['posts'] } }) + +// Page B: /dashboard +const recentPosts = await fetch('/api/posts?limit=5', { + next: { tags: ['posts'] }, +}) +``` + +After calling `revalidatePath('/blog')`: + +- **Page A (/blog)**: Shows fresh data (page re-rendered) +- **Page B (/dashboard)**: Still shows stale data (cache tag 'posts' not invalidated) + +### Building revalidation utilities + +`revalidatePath` and `revalidateTag` are complementary primitives that are often used together in utility functions to ensure comprehensive data consistency across your application: + +```ts +'use server' + +import { revalidatePath, revalidateTag } from 'next/cache' + +export async function updatePost() { + await updatePostInDatabase() + + revalidatePath('/blog') // Refresh the blog page + revalidateTag('posts') // Refresh all pages using 'posts' tag +} +``` + +This pattern ensures that both the specific page and any other pages using the same data remain consistent. + ## Examples ### Revalidating A Specific URL diff --git a/docs/01-app/03-api-reference/04-functions/revalidateTag.mdx b/docs/01-app/03-api-reference/04-functions/revalidateTag.mdx index 387ed98ef3aa..1d31e033248c 100644 --- a/docs/01-app/03-api-reference/04-functions/revalidateTag.mdx +++ b/docs/01-app/03-api-reference/04-functions/revalidateTag.mdx @@ -5,9 +5,13 @@ description: API Reference for the revalidateTag function. `revalidateTag` allows you to purge [cached data](/docs/app/guides/caching) on-demand for a specific cache tag. -> **Good to know**: -> -> - `revalidateTag` only invalidates the cache when the path is next visited. This means calling `revalidateTag` with a dynamic route segment will not immediately trigger many revalidations at once. The invalidation only happens when the path is next visited. +## Usage + +`revalidateTag` can be called in Server Functions and Route Handlers. + +`revalidateTag` cannot be called in Client Components or Middleware, as it only works in server environments. + +> **Good to know**: `revalidateTag` marks tagged data as stale, but fresh data is only fetched when pages using that tag are next visited. This means calling `revalidateTag` will not immediately trigger many revalidations at once. The invalidation only happens when any page using that tag is next visited. ## Parameters @@ -15,7 +19,7 @@ description: API Reference for the revalidateTag function. revalidateTag(tag: string): void; ``` -- `tag`: A string representing the cache tag associated with the data you want to revalidate. Must be less than or equal to 256 characters. This value is case-sensitive. +- `tag`: A string representing the cache tag associated with the data you want to revalidate. Must not exceed 256 characters. This value is case-sensitive. You can add tags to `fetch` as follows: @@ -27,6 +31,12 @@ fetch(url, { next: { tags: [...] } }); `revalidateTag` does not return a value. +## Relationship with `revalidatePath` + +`revalidateTag` revalidates data with specific tags across all pages that use those tags, while [`revalidatePath`](/docs/app/api-reference/functions/revalidatePath) revalidates specific page or layout paths. + +> **Good to know**: These functions serve different purposes and may need to be used together for comprehensive data consistency. For detailed examples and considerations, see [Relationship with revalidateTag](/docs/app/api-reference/functions/revalidatePath#relationship-with-revalidatetag). + ## Examples ### Server Action @@ -61,8 +71,17 @@ import { revalidateTag } from 'next/cache' export async function GET(request: NextRequest) { const tag = request.nextUrl.searchParams.get('tag') - revalidateTag(tag) - return Response.json({ revalidated: true, now: Date.now() }) + + if (tag) { + revalidateTag(tag) + return Response.json({ revalidated: true, now: Date.now() }) + } + + return Response.json({ + revalidated: false, + now: Date.now(), + message: 'Missing tag to revalidate', + }) } ``` @@ -71,7 +90,16 @@ import { revalidateTag } from 'next/cache' export async function GET(request) { const tag = request.nextUrl.searchParams.get('tag') - revalidateTag(tag) - return Response.json({ revalidated: true, now: Date.now() }) + + if (tag) { + revalidateTag(tag) + return Response.json({ revalidated: true, now: Date.now() }) + } + + return Response.json({ + revalidated: false, + now: Date.now(), + message: 'Missing tag to revalidate', + }) } ```