docs: Clarify revalidatePath (vercel#82142)

Fixes: vercel#81776

Author: icyJoseph

docs/01-app/03-api-reference/04-functions/revalidatePath.mdx

@@ -5,25 +5,83 @@ 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).
+> - **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 revalidations at once. The invalidation only happens when the path is next visited.
 
 ## Parameters
 
 ```tsx
 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.
 
+## 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
 
 ### Revalidating A Specific URL
@@ -67,7 +125,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'

docs/01-app/03-api-reference/04-functions/revalidateTag.mdx

@@ -5,17 +5,21 @@ 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
 
 ```tsx
 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',
+  })
 }
 ```