Unverified Commit 1f8ea2a1 authored by Joseph's avatar Joseph Committed by GitHub

docs: Clarify revalidatePath (#82142)

Fixes: https://github.com/vercel/next.js/issues/81776
parent 75259947
...@@ -5,11 +5,16 @@ description: API Reference for the revalidatePath function. ...@@ -5,11 +5,16 @@ description: API Reference for the revalidatePath function.
`revalidatePath` allows you to purge [cached data](/docs/app/guides/caching) on-demand for a specific path. `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**: > **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. > - **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.
> - 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. > - **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.
> - Using `revalidatePath` invalidates **only the specific path** in the [server-side Route Cache](/docs/app/guides/caching#full-route-cache).
## Parameters ## Parameters
...@@ -17,13 +22,66 @@ description: API Reference for the revalidatePath function. ...@@ -17,13 +22,66 @@ description: API Reference for the revalidatePath function.
revalidatePath(path: string, type?: 'page' | 'layout'): void; 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`. - `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 ## Returns
`revalidatePath` does not return a value. `revalidatePath` does not return a value.
## What can be revalidated
The path parameter can point to pages, layouts, or route handlers:
- **Pages**: Revalidates the specific page
- **Layouts**: Revalidates the layout and all pages beneath it
- **GET Route Handlers**: Only if they're statically generated
## 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('https://api.vercel.app/blog', {
next: { tags: ['posts'] },
})
// Page B: /dashboard
const recentPosts = await fetch('https://api.vercel.app/blog?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 ## Examples
### Revalidating A Specific URL ### Revalidating A Specific URL
...@@ -67,7 +125,7 @@ revalidatePath('/', 'layout') ...@@ -67,7 +125,7 @@ revalidatePath('/', 'layout')
This will purge the Client-side Router Cache, and revalidate the Data Cache on the next page visit. 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 ```ts filename="app/actions.ts" switcher
'use server' 'use server'
......
...@@ -5,9 +5,13 @@ description: API Reference for the revalidateTag function. ...@@ -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. `revalidateTag` allows you to purge [cached data](/docs/app/guides/caching) on-demand for a specific cache tag.
> **Good to know**: ## Usage
>
> - `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. `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 ## Parameters
...@@ -15,7 +19,7 @@ description: API Reference for the revalidateTag function. ...@@ -15,7 +19,7 @@ description: API Reference for the revalidateTag function.
revalidateTag(tag: string): void; 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: You can add tags to `fetch` as follows:
...@@ -27,6 +31,12 @@ fetch(url, { next: { tags: [...] } }); ...@@ -27,6 +31,12 @@ fetch(url, { next: { tags: [...] } });
`revalidateTag` does not return a value. `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 ## Examples
### Server Action ### Server Action
...@@ -61,8 +71,17 @@ import { revalidateTag } from 'next/cache' ...@@ -61,8 +71,17 @@ import { revalidateTag } from 'next/cache'
export async function GET(request: NextRequest) { export async function GET(request: NextRequest) {
const tag = request.nextUrl.searchParams.get('tag') 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' ...@@ -71,7 +90,16 @@ import { revalidateTag } from 'next/cache'
export async function GET(request) { export async function GET(request) {
const tag = request.nextUrl.searchParams.get('tag') 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',
})
} }
``` ```
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment