From f2e3ee11e3451a539ddaec427f171edade88b000 Mon Sep 17 00:00:00 2001
From: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Date: Mon, 2 Dec 2024 17:40:23 +0000
Subject: [PATCH 01/25] Clean up

---
 docs/01-app/03-api-reference/01-directives/use-cache.mdx | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/docs/01-app/03-api-reference/01-directives/use-cache.mdx b/docs/01-app/03-api-reference/01-directives/use-cache.mdx
index aa8d95e1cec1a..97466f9f6ef77 100644
--- a/docs/01-app/03-api-reference/01-directives/use-cache.mdx
+++ b/docs/01-app/03-api-reference/01-directives/use-cache.mdx
@@ -69,13 +69,12 @@ export async function getData() {
 
 ## Examples
 
-### Caching entire routes with `use cache`
+### Caching an entire route with `use cache`
 
 To prerender an entire route, add `use cache` to the top **both** the `layout` and `page` files. Each of these segments are treated as separate entry points in your application, and will be cached independently.
 
 ```tsx filename="app/layout.tsx" switcher
 'use cache'
-import { unstable_cacheLife as cacheLife } from 'next/cache'
 
 export default function Layout({ children }: { children: ReactNode }) {
   return <div>{children}</div>
@@ -84,7 +83,6 @@ export default function Layout({ children }: { children: ReactNode }) {
 
 ```jsx filename="app/page.tsx" switcher
 'use cache'
-import { unstable_cacheLife as cacheLife } from 'next/cache'
 
 export default function Layout({ children }) {
   return <div>{children}</div>

From 914365463fffe9ef0de350eab491d14fec2d1cf2 Mon Sep 17 00:00:00 2001
From: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Date: Mon, 2 Dec 2024 17:44:56 +0000
Subject: [PATCH 02/25] Create 07-caching-and-revalidating.mdx

---
 .../07-caching-and-revalidating.mdx                 | 13 +++++++++++++
 1 file changed, 13 insertions(+)
 create mode 100644 docs/01-app/01-getting-started/07-caching-and-revalidating.mdx

diff --git a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
new file mode 100644
index 0000000000000..4d70dc2b719a4
--- /dev/null
+++ b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
@@ -0,0 +1,13 @@
+---
+title: How to cache and revalidate content
+nav_title: Caching and Revalidating
+description: Learn how to cache and revalidate functions and components in your Next.js application.
+related:
+  links:
+    - app/api-reference/config/next-config-js/dynamicIO
+    - app/api-reference/directives/use-cache
+    - app/api-reference/functions/cacheLife
+    - app/api-reference/functions/cacheTag
+---
+
+> **Warning:** The content below assumes the [`dynamicIO` config option](/docs/app/api-reference/config/next-config-js/dynamicIO) is enabled in your application. This option was introduced in Next.js 15 canary.

From 3b820a38f042d4314156971f850f15c3f957dee4 Mon Sep 17 00:00:00 2001
From: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Date: Mon, 2 Dec 2024 17:50:06 +0000
Subject: [PATCH 03/25] Add `caching` section (wip)

---
 .../07-caching-and-revalidating.mdx           | 56 +++++++++++++++++++
 1 file changed, 56 insertions(+)

diff --git a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
index 4d70dc2b719a4..a90edc1226041 100644
--- a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
+++ b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
@@ -11,3 +11,59 @@ related:
 ---
 
 > **Warning:** The content below assumes the [`dynamicIO` config option](/docs/app/api-reference/config/next-config-js/dynamicIO) is enabled in your application. This option was introduced in Next.js 15 canary.
+
+## Caching
+
+In Next.js, you can cache the output of a dynamic [component](#caching-the-render-output-of-a-component) or [function](#caching-the-return-value-of-a-function) to improve performance and reduce the need to re-execute work for every user request.
+
+Caching is useful for content that doesn't change often or is shared across multiple users, as you can **prerender** at build time, and reuse the static result for all requests.
+
+To mark a function or component as cacheable, you can use the [`'use cache'`](/docs/app/api-reference/directives/use-cache) directive.
+
+## Caching the return value of a function
+
+You can cache the return value of an **asynchronous** function, including data requests, by adding the `'use cache'` directive inside the function body:
+
+```ts filename="app/lib/data.ts" switcher
+export async function getPosts(slug: string) {
+  'use cache'
+  const data = await fetch(`/api/posts/${slug}`)
+  return data.json()
+}
+```
+
+```js filename="app/lib/data.js" switcher
+export async function getPosts(slug) {
+  'use cache'
+  const data = await fetch(`/api/posts/${slug}`)
+  return data.json()
+}
+```
+
+By adding `'use cache'` to the function body, you can reuse the function throughout your code and the same cache entry will be reused as long as the arguments are the same.
+
+You can also cache all functions within a file by adding the `'use cache'` directive at the top of the file:
+
+```ts filename="app/lib/data.ts" switcher
+'use cache'
+
+export async function getPosts(slug: string) {
+  const data = await fetch(`/api/posts/${slug}`)
+  return data.json()
+}
+
+// Other functions in this file will also be cached
+// ...
+```
+
+```js filename="app/lib/data.js" switcher
+'use cache'
+
+export async function getPosts(slug) {
+  const data = await fetch(`/api/posts/${slug}`)
+  return data.json()
+}
+
+// Other functions in this file will also be cached
+// ...
+```

From b72324b64b7081001101fa9550d87ad1f74df562 Mon Sep 17 00:00:00 2001
From: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Date: Fri, 6 Dec 2024 14:36:01 +0000
Subject: [PATCH 04/25] Add API reference description

---
 docs/01-app/01-getting-started/07-caching-and-revalidating.mdx | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
index a90edc1226041..4516961e0d006 100644
--- a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
+++ b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
@@ -3,6 +3,8 @@ title: How to cache and revalidate content
 nav_title: Caching and Revalidating
 description: Learn how to cache and revalidate functions and components in your Next.js application.
 related:
+  title: API Reference
+  description: Learn more about the features mentioned in this page by reading the API Reference.
   links:
     - app/api-reference/config/next-config-js/dynamicIO
     - app/api-reference/directives/use-cache

From a8e6cfe61348202a5903cb41360a39fd48bf9d02 Mon Sep 17 00:00:00 2001
From: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Date: Fri, 6 Dec 2024 14:40:05 +0000
Subject: [PATCH 05/25] Clean up

---
 .../01-app/01-getting-started/07-caching-and-revalidating.mdx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
index 4516961e0d006..6aca1f48bf9d2 100644
--- a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
+++ b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
@@ -16,9 +16,9 @@ related:
 
 ## Caching
 
-In Next.js, you can cache the output of a dynamic [component](#caching-the-render-output-of-a-component) or [function](#caching-the-return-value-of-a-function) to improve performance and reduce the need to re-execute work for every user request.
+In Next.js, you can cache the output of a [component](/docs/app/building-your-application/caching/caching-components) or [function](/docs/app/building-your-application/caching/caching-data) to reduce the need to re-execute work for every user request.
 
-Caching is useful for content that doesn't change often or is shared across multiple users, as you can **prerender** at build time, and reuse the static result for all requests.
+Caching is useful for content that doesn't change often or is shared across multiple users, as you can **prerender** at build time, and improve performance by reusing the static content for all requests.
 
 To mark a function or component as cacheable, you can use the [`'use cache'`](/docs/app/api-reference/directives/use-cache) directive.
 

From 8f1c93a67d1afef142ed341134fac015157c4645 Mon Sep 17 00:00:00 2001
From: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Date: Fri, 6 Dec 2024 14:40:48 +0000
Subject: [PATCH 06/25] Add caching examples

---
 .../07-caching-and-revalidating.mdx           | 103 ++++++++++++++++--
 1 file changed, 95 insertions(+), 8 deletions(-)

diff --git a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
index 6aca1f48bf9d2..0d0d79fb97afa 100644
--- a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
+++ b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
@@ -22,6 +22,89 @@ Caching is useful for content that doesn't change often or is shared across mult
 
 To mark a function or component as cacheable, you can use the [`'use cache'`](/docs/app/api-reference/directives/use-cache) directive.
 
+## Caching the render output of a component
+
+You can cache the render output of an **asynchronous** [Server Component](https://react.dev/reference/rsc/server-components) by adding the `'use cache'` directive inside the component body:
+
+```tsx filename="app/blog/page.tsx" highlight={4} switcher
+import { getPosts } from '@/app/lib/data'
+
+export default async function Page() {
+  'use cache'
+  const posts = await getPosts()
+
+  return (
+    <ul>
+      {posts.map((post) => (
+        <li key={post.id}>{post.title}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+```js filename="app/blog/page.js" highlight={4} switcher
+import { getPosts } from '@/app/lib/data'
+
+export default async function Page() {
+  'use cache'
+  const posts = await getPosts()
+  return (
+    <ul>
+      {posts.map((post) => (
+        <li key={post.id}>{post.title}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+Alternatively, you can add the `'use cache'` directive at the top of the file to mark all components in the file as cacheable:
+
+```tsx filename="app/blog/page.tsx" highlight={1} switcher
+'use cache'
+
+import { getPosts } from '@/app/lib/data'
+
+export default async function Page() {
+  const posts = await getPosts()
+
+  return <Posts posts={posts} />
+}
+
+async function Posts({ posts }) {
+  return (
+    <ul>
+      {posts.map((post) => (
+        <li key={post.id}>{post.title}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+```js filename="app/blog/page.js" highlight={1} switcher
+'use cache'
+
+import { getPosts } from '@/app/lib/data'
+
+export default async function Page() {
+  const posts = await getPosts()
+
+  return <Posts posts={posts} />
+}
+
+async function Posts({ posts }) {
+  return (
+    <ul>
+      {posts.map((post) => (
+        <li key={post.id}>{post.title}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
 ## Caching the return value of a function
 
 You can cache the return value of an **asynchronous** function, including data requests, by adding the `'use cache'` directive inside the function body:
@@ -49,23 +132,27 @@ You can also cache all functions within a file by adding the `'use cache'` direc
 ```ts filename="app/lib/data.ts" switcher
 'use cache'
 
-export async function getPosts(slug: string) {
-  const data = await fetch(`/api/posts/${slug}`)
+export async function getPosts() {
+  const data = await fetch(`/api/posts`)
   return data.json()
 }
 
-// Other functions in this file will also be cached
-// ...
+export async function getPostBySlug(slug: string) {
+  const data = await fetch(`/api/posts/${slug}`)
+  return data.json()
+}
 ```
 
 ```js filename="app/lib/data.js" switcher
 'use cache'
 
-export async function getPosts(slug) {
-  const data = await fetch(`/api/posts/${slug}`)
+export async function getPosts() {
+  const data = await fetch(`/api/posts/`)
   return data.json()
 }
 
-// Other functions in this file will also be cached
-// ...
+export async function getPostBySlug(slug: string) {
+  const data = await fetch(`/api/posts/${slug}`)
+  return data.json()
+}
 ```

From 7254afb8bf4b29723380e530e8ca835ed109ee4a Mon Sep 17 00:00:00 2001
From: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Date: Fri, 6 Dec 2024 15:06:09 +0000
Subject: [PATCH 07/25] Add revalidation section

---
 .../01-getting-started/07-caching-and-revalidating.mdx   | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
index 0d0d79fb97afa..a74104602f21b 100644
--- a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
+++ b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
@@ -156,3 +156,12 @@ export async function getPostBySlug(slug: string) {
   return data.json()
 }
 ```
+
+## Revalidating
+
+Revalidation allows you to update cached content without having to rebuild your entire application. It's useful for content that _sometimes_ changes, but would benefit from being cached to improve performance.
+
+In Next.js, there are two types of revalidation:
+
+- **Time-based**: Based on a time interval (e.g. every hour).
+- **On-demand**: Triggered by a specific event (e.g. a CMS webhook).

From 23581d519616324146079bb1896dff50d1bfda0a Mon Sep 17 00:00:00 2001
From: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Date: Fri, 6 Dec 2024 15:06:25 +0000
Subject: [PATCH 08/25] Add time-based revalidation examples

---
 .../07-caching-and-revalidating.mdx           | 30 +++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
index a74104602f21b..f337d29026893 100644
--- a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
+++ b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
@@ -165,3 +165,33 @@ In Next.js, there are two types of revalidation:
 
 - **Time-based**: Based on a time interval (e.g. every hour).
 - **On-demand**: Triggered by a specific event (e.g. a CMS webhook).
+
+## Time-based Revalidation
+
+You can use the [`cacheLife` function](/docs/app/api-reference/functions/cacheLife) to define a time interval for how long a cached value should remain stale before it's revalidated.
+
+`cacheLife` comes with [default cache profiles](/docs/app/api-reference/functions/cacheLife#default-cache-profiles) such as `'hour'`, `'day'`, and `'week'` which can be [customized](/docs/app/api-reference/functions/cacheLife#custom-cache-profiles), if needed.
+
+To use `cacheLife`, import it from `next/cache` and nest it within the scope of the `'use cache'` directive and a function. For example, to cache the blog page for one hour:
+
+```tsx filename="app/blog/page.tsx" highlight={3,6} switcher
+'use cache'
+
+import { cacheLife } from 'next/cache'
+
+export default async function Page() {
+  cacheLife('hour')
+  return <Posts posts={posts} />
+}
+```
+
+```jsx filename="app/blog/page.js" highlight={3,6} switcher
+'use cache'
+
+import { cacheLife } from 'next/cache'
+
+export default async function Page() {
+  cacheLife('hour')
+  return <Posts posts={posts} />
+}
+```

From 3a4a981bf79768972b1a5383b8941012a29c9d99 Mon Sep 17 00:00:00 2001
From: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Date: Wed, 11 Dec 2024 11:23:52 +0000
Subject: [PATCH 09/25] Clean up

---
 .../07-caching-and-revalidating.mdx              | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
index f337d29026893..fa7d7242b051b 100644
--- a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
+++ b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
@@ -16,15 +16,15 @@ related:
 
 ## Caching
 
-In Next.js, you can cache the output of a [component](/docs/app/building-your-application/caching/caching-components) or [function](/docs/app/building-your-application/caching/caching-data) to reduce the need to re-execute work for every user request.
+In Next.js, you can cache the output of a [component](#components) or [function](#functions) to reduce the need to re-execute work for every user request.
 
-Caching is useful for content that doesn't change often or is shared across multiple users, as you can **prerender** at build time, and improve performance by reusing the static content for all requests.
+Caching is useful for content that doesn't change often or is shared across multiple users, as you can **prerender** at build time, and reuse the static content for all requests.
 
 To mark a function or component as cacheable, you can use the [`'use cache'`](/docs/app/api-reference/directives/use-cache) directive.
 
-## Caching the render output of a component
+### Components
 
-You can cache the render output of an **asynchronous** [Server Component](https://react.dev/reference/rsc/server-components) by adding the `'use cache'` directive inside the component body:
+You can add `'use cache'` to an **asynchronous** [Server Component](https://react.dev/reference/rsc/server-components) to cache the **component's render output**:
 
 ```tsx filename="app/blog/page.tsx" highlight={4} switcher
 import { getPosts } from '@/app/lib/data'
@@ -105,7 +105,7 @@ async function Posts({ posts }) {
 }
 ```
 
-## Caching the return value of a function
+### Functions
 
 You can cache the return value of an **asynchronous** function, including data requests, by adding the `'use cache'` directive inside the function body:
 
@@ -125,9 +125,9 @@ export async function getPosts(slug) {
 }
 ```
 
-By adding `'use cache'` to the function body, you can reuse the function throughout your code and the same cache entry will be reused as long as the arguments are the same.
+With the approach above, you can call the function throughout your application and the same cache entry will be reused as long as the arguments are the same.
 
-You can also cache all functions within a file by adding the `'use cache'` directive at the top of the file:
+Alternatively, you can also cache all functions within a file by adding the `'use cache'` directive at the top of the file:
 
 ```ts filename="app/lib/data.ts" switcher
 'use cache'
@@ -159,7 +159,7 @@ export async function getPostBySlug(slug: string) {
 
 ## Revalidating
 
-Revalidation allows you to update cached content without having to rebuild your entire application. It's useful for content that _sometimes_ changes, but would benefit from being cached to improve performance.
+Revalidation allows you to update cached content without having to rebuild your entire application. It's useful for content that _sometimes_ changes, but would benefit from being cached to improve your application'sperformance.
 
 In Next.js, there are two types of revalidation:
 

From 1fbc5fdfe7906b51a707f5ae768515c4ccd21478 Mon Sep 17 00:00:00 2001
From: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Date: Wed, 11 Dec 2024 12:05:45 +0000
Subject: [PATCH 10/25] Add on-demand revalidation example

---
 .../07-caching-and-revalidating.mdx           | 100 ++++++++++++++++++
 1 file changed, 100 insertions(+)

diff --git a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
index fa7d7242b051b..8a5f229d89fe2 100644
--- a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
+++ b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
@@ -195,3 +195,103 @@ export default async function Page() {
   return <Posts posts={posts} />
 }
 ```
+
+## On-demand Revalidation
+
+You can use the [`cacheTag` function](/docs/app/api-reference/functions/cacheTag) to define a tag for a cache entry. The entry can then be purged using the [`expireTag`](/docs/app/api-reference/functions/expireTag) in another part of your application such a [Server Action](https://react.dev/reference/rsc/server-functions) or [Route Handler](/docs/app/building-your-application/routing/route-handlers).
+
+For example, to update the list of blog posts once a new post is created, add the `cacheTag` function to the component that renders the list of posts:
+
+```tsx filename="app/ui/posts.tsx" switcher
+'use cache'
+
+import { cacheTag } from 'next/cache'
+
+export function Posts({ posts }) {
+  cacheTag('blog-posts')
+  return (
+    <ul>
+      {posts.map((post) => (
+        <li key={post.id}>{post.title}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+```jsx filename="app/ui/posts.js" switcher
+'use cache'
+
+import { cacheTag } from 'next/cache'
+
+export function Posts({ posts }) {
+  cacheTag('blog-posts')
+  return (
+    <ul>
+      {posts.map((post) => (
+        <li key={post.id}>{post.title}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+Then, in the Server Action, call `expireTag` to purge the cache entry:
+
+```tsx filename="app/actions.ts" switcher
+'use server'
+
+import { expireTag } from 'next/cache'
+
+export async function createPost() {
+  // Mutate data
+  // ...
+
+  // Purge cache
+  expireTag('blog-posts')
+}
+```
+
+```jsx filename="app/actions.js" switcher
+'use server'
+
+import { expireTag } from 'next/cache'
+
+export async function createPost() {
+  // Mutate data
+  // ...
+
+  // Purge cache
+  expireTag('blog-posts')
+}
+```
+
+Alternatively, you can call the [`expirePath`](/docs/app/api-reference/functions/unstable_expirePath) function to purge the whole `/blog` route (in which case you don't need to add `cacheTag`):
+
+```tsx filename="app/actions.ts" switcher
+'use server'
+
+import { expireTag } from 'next/cache'
+
+export async function createPost() {
+  // Mutate data
+  // ...
+
+  // Purge cache
+  expirePath('/blog')
+}
+```
+
+```tsx filename="app/actions.ts" switcher
+'use server'
+
+import { expireTag } from 'next/cache'
+
+export async function createPost() {
+  // Mutate data
+  // ...
+
+  // Purge cache
+  expirePath('/blog')
+}
+```

From d79be660dc9dbf24fcdcc5fac6384e4ef87fe0f2 Mon Sep 17 00:00:00 2001
From: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Date: Wed, 11 Dec 2024 12:05:52 +0000
Subject: [PATCH 11/25] Clean up

---
 .../07-caching-and-revalidating.mdx                  | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
index 8a5f229d89fe2..03fc96b867f69 100644
--- a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
+++ b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
@@ -1,7 +1,7 @@
 ---
-title: How to cache and revalidate content
+title: How to cache and revalidate components and functions
 nav_title: Caching and Revalidating
-description: Learn how to cache and revalidate functions and components in your Next.js application.
+description: Learn how to cache and revalidate components and functions in your Next.js application.
 related:
   title: API Reference
   description: Learn more about the features mentioned in this page by reading the API Reference.
@@ -10,6 +10,8 @@ related:
     - app/api-reference/directives/use-cache
     - app/api-reference/functions/cacheLife
     - app/api-reference/functions/cacheTag
+    - app/api-reference/functions/unstable_expireTag
+    - app/api-reference/functions/unstable_expirePath
 ---
 
 > **Warning:** The content below assumes the [`dynamicIO` config option](/docs/app/api-reference/config/next-config-js/dynamicIO) is enabled in your application. This option was introduced in Next.js 15 canary.
@@ -170,12 +172,12 @@ In Next.js, there are two types of revalidation:
 
 You can use the [`cacheLife` function](/docs/app/api-reference/functions/cacheLife) to define a time interval for how long a cached value should remain stale before it's revalidated.
 
-`cacheLife` comes with [default cache profiles](/docs/app/api-reference/functions/cacheLife#default-cache-profiles) such as `'hour'`, `'day'`, and `'week'` which can be [customized](/docs/app/api-reference/functions/cacheLife#custom-cache-profiles), if needed.
+`cacheLife` comes with [default cache profiles](/docs/app/api-reference/functions/cacheLife#default-cache-profiles) such as `'hour'`, `'day'`, and `'week'`. These profiles can be [customized](/docs/app/api-reference/functions/cacheLife#custom-cache-profiles), if needed.
 
-To use `cacheLife`, import it from `next/cache` and nest it within the scope of the `'use cache'` directive and a function. For example, to cache the blog page for one hour:
+To use `cacheLife`, import it from `next/cache` and nest it within the **scope** of the `'use cache'` directive and the function. For example, to revalidate the blog page after one hour:
 
 ```tsx filename="app/blog/page.tsx" highlight={3,6} switcher
-'use cache'
+'use cache'o/>:.
 
 import { cacheLife } from 'next/cache'
 

From 5d0eaa02b604f68a009ca2658a2f21cb3cb79e6c Mon Sep 17 00:00:00 2001
From: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Date: Wed, 11 Dec 2024 13:51:36 +0000
Subject: [PATCH 12/25] Remove mentions of expireTag and expirePath

- We don't want to talk about these just yet
---
 .../07-caching-and-revalidating.mdx           | 24 +++++++++----------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
index 03fc96b867f69..04615c9cf8061 100644
--- a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
+++ b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
@@ -10,8 +10,8 @@ related:
     - app/api-reference/directives/use-cache
     - app/api-reference/functions/cacheLife
     - app/api-reference/functions/cacheTag
-    - app/api-reference/functions/unstable_expireTag
-    - app/api-reference/functions/unstable_expirePath
+    - app/api-reference/functions/revalidateTag
+    - app/api-reference/functions/revalidatePath
 ---
 
 > **Warning:** The content below assumes the [`dynamicIO` config option](/docs/app/api-reference/config/next-config-js/dynamicIO) is enabled in your application. This option was introduced in Next.js 15 canary.
@@ -200,7 +200,7 @@ export default async function Page() {
 
 ## On-demand Revalidation
 
-You can use the [`cacheTag` function](/docs/app/api-reference/functions/cacheTag) to define a tag for a cache entry. The entry can then be purged using the [`expireTag`](/docs/app/api-reference/functions/expireTag) in another part of your application such a [Server Action](https://react.dev/reference/rsc/server-functions) or [Route Handler](/docs/app/building-your-application/routing/route-handlers).
+You can use the [`cacheTag` function](/docs/app/api-reference/functions/cacheTag) to define a tag for a cache entry. The entry can then be purged using the [`revalidateTag`](/docs/app/api-reference/functions/revalidateTag) function in another part of your application such a [Server Action](https://react.dev/reference/rsc/server-functions) or [Route Handler](/docs/app/building-your-application/routing/route-handlers).
 
 For example, to update the list of blog posts once a new post is created, add the `cacheTag` function to the component that renders the list of posts:
 
@@ -238,56 +238,56 @@ export function Posts({ posts }) {
 }
 ```
 
-Then, in the Server Action, call `expireTag` to purge the cache entry:
+Then, in the Server Action to create a new post, call `revalidateTag` to purge the cache entry:
 
 ```tsx filename="app/actions.ts" switcher
 'use server'
 
-import { expireTag } from 'next/cache'
+import { revalidateTag } from 'next/cache'
 
 export async function createPost() {
   // Mutate data
   // ...
 
   // Purge cache
-  expireTag('blog-posts')
+  revalidateTag('blog-posts')
 }
 ```
 
 ```jsx filename="app/actions.js" switcher
 'use server'
 
-import { expireTag } from 'next/cache'
+import { revalidateTag } from 'next/cache'
 
 export async function createPost() {
   // Mutate data
   // ...
 
   // Purge cache
-  expireTag('blog-posts')
+  revalidateTag('blog-posts')
 }
 ```
 
-Alternatively, you can call the [`expirePath`](/docs/app/api-reference/functions/unstable_expirePath) function to purge the whole `/blog` route (in which case you don't need to add `cacheTag`):
+Alternatively, you can call the [`revalidatePath`](/docs/app/api-reference/functions/revalidatePath) function to purge the whole `/blog` route (in which case you don't need `cacheTag`):
 
 ```tsx filename="app/actions.ts" switcher
 'use server'
 
-import { expireTag } from 'next/cache'
+import { revalidatePath } from 'next/cache'
 
 export async function createPost() {
   // Mutate data
   // ...
 
   // Purge cache
-  expirePath('/blog')
+  revalidatePath('/blog')
 }
 ```
 
 ```tsx filename="app/actions.ts" switcher
 'use server'
 
-import { expireTag } from 'next/cache'
+import { revalidatePath } from 'next/cache'
 
 export async function createPost() {
   // Mutate data

From 5481a23874d8bcbf72a2b322ba6967044e2ed2c5 Mon Sep 17 00:00:00 2001
From: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Date: Wed, 11 Dec 2024 13:57:08 +0000
Subject: [PATCH 13/25] Clean up

---
 .../07-caching-and-revalidating.mdx                | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
index 04615c9cf8061..87a4131e643bc 100644
--- a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
+++ b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
@@ -20,13 +20,13 @@ related:
 
 In Next.js, you can cache the output of a [component](#components) or [function](#functions) to reduce the need to re-execute work for every user request.
 
-Caching is useful for content that doesn't change often or is shared across multiple users, as you can **prerender** at build time, and reuse the static content for all requests.
+Caching is useful for data that doesn't change often or is shared across multiple users, as you can **prerender** at build time, and reuse the static content for all requests.
 
 To mark a function or component as cacheable, you can use the [`'use cache'`](/docs/app/api-reference/directives/use-cache) directive.
 
 ### Components
 
-You can add `'use cache'` to an **asynchronous** [Server Component](https://react.dev/reference/rsc/server-components) to cache the **component's render output**:
+You can add `'use cache'` to an **asynchronous** [Server Component](https://react.dev/reference/rsc/server-components) to cache the component's render output:
 
 ```tsx filename="app/blog/page.tsx" highlight={4} switcher
 import { getPosts } from '@/app/lib/data'
@@ -127,7 +127,7 @@ export async function getPosts(slug) {
 }
 ```
 
-With the approach above, you can call the function throughout your application and the same cache entry will be reused as long as the arguments are the same.
+With the approach above, you can call the function throughout your application code and the same cache entry will be reused as long as the arguments are the same.
 
 Alternatively, you can also cache all functions within a file by adding the `'use cache'` directive at the top of the file:
 
@@ -165,8 +165,8 @@ Revalidation allows you to update cached content without having to rebuild your
 
 In Next.js, there are two types of revalidation:
 
-- **Time-based**: Based on a time interval (e.g. every hour).
-- **On-demand**: Triggered by a specific event (e.g. a CMS webhook).
+- [Time-based](#time-based-revalidation): Based on a time interval (e.g. every hour).
+- [On-demand](#on-demand-revalidation): Triggered by a specific event (e.g. a CMS webhook).
 
 ## Time-based Revalidation
 
@@ -200,7 +200,7 @@ export default async function Page() {
 
 ## On-demand Revalidation
 
-You can use the [`cacheTag` function](/docs/app/api-reference/functions/cacheTag) to define a tag for a cache entry. The entry can then be purged using the [`revalidateTag`](/docs/app/api-reference/functions/revalidateTag) function in another part of your application such a [Server Action](https://react.dev/reference/rsc/server-functions) or [Route Handler](/docs/app/building-your-application/routing/route-handlers).
+You can use the [`cacheTag` function](/docs/app/api-reference/functions/cacheTag) to define a tag for a cache entry. The entry can then be revalidated using the [`revalidateTag`](/docs/app/api-reference/functions/revalidateTag) function in another part of your application, such as a [Server Action](https://react.dev/reference/rsc/server-functions) or [Route Handler](/docs/app/building-your-application/routing/route-handlers).
 
 For example, to update the list of blog posts once a new post is created, add the `cacheTag` function to the component that renders the list of posts:
 
@@ -238,7 +238,7 @@ export function Posts({ posts }) {
 }
 ```
 
-Then, in the Server Action to create a new post, call `revalidateTag` to purge the cache entry:
+Then, in the Server Action to create a new post, call `revalidateTag` using the same tag to purge the cache entry:
 
 ```tsx filename="app/actions.ts" switcher
 'use server'

From 8c78cc066123f6897aa9a42b7b7497ff90080abe Mon Sep 17 00:00:00 2001
From: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Date: Tue, 17 Dec 2024 10:08:07 +0000
Subject: [PATCH 14/25] Update caching description

---
 docs/01-app/01-getting-started/07-caching-and-revalidating.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
index 87a4131e643bc..171d4c9d326c8 100644
--- a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
+++ b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
@@ -20,7 +20,7 @@ related:
 
 In Next.js, you can cache the output of a [component](#components) or [function](#functions) to reduce the need to re-execute work for every user request.
 
-Caching is useful for data that doesn't change often or is shared across multiple users, as you can **prerender** at build time, and reuse the static content for all requests.
+Caching is useful for data that doesn't change often or is shared across users, and functions that are computationally intensive, as you can reuse the result and reduce the time it takes to respond to requests.
 
 To mark a function or component as cacheable, you can use the [`'use cache'`](/docs/app/api-reference/directives/use-cache) directive.
 

From fb5e279f5832c5ae3d4bdd4db8ee72dd504f386e Mon Sep 17 00:00:00 2001
From: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Date: Tue, 17 Dec 2024 10:08:20 +0000
Subject: [PATCH 15/25] Use api.vercel.app

---
 .../07-caching-and-revalidating.mdx                  | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
index 171d4c9d326c8..604bc60491f92 100644
--- a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
+++ b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
@@ -114,7 +114,7 @@ You can cache the return value of an **asynchronous** function, including data r
 ```ts filename="app/lib/data.ts" switcher
 export async function getPosts(slug: string) {
   'use cache'
-  const data = await fetch(`/api/posts/${slug}`)
+  const data = await fetch(`https://api.vercel.app/posts/${slug}`)
   return data.json()
 }
 ```
@@ -122,7 +122,7 @@ export async function getPosts(slug: string) {
 ```js filename="app/lib/data.js" switcher
 export async function getPosts(slug) {
   'use cache'
-  const data = await fetch(`/api/posts/${slug}`)
+  const data = await fetch(`https://api.vercel.app/posts/${slug}`)
   return data.json()
 }
 ```
@@ -135,12 +135,12 @@ Alternatively, you can also cache all functions within a file by adding the `'us
 'use cache'
 
 export async function getPosts() {
-  const data = await fetch(`/api/posts`)
+  const data = await fetch(`https://api.vercel.app/posts`)
   return data.json()
 }
 
 export async function getPostBySlug(slug: string) {
-  const data = await fetch(`/api/posts/${slug}`)
+  const data = await fetch(`https://api.vercel.app/posts/${slug}`)
   return data.json()
 }
 ```
@@ -149,12 +149,12 @@ export async function getPostBySlug(slug: string) {
 'use cache'
 
 export async function getPosts() {
-  const data = await fetch(`/api/posts/`)
+  const data = await fetch(`https://api.vercel.app/posts/`)
   return data.json()
 }
 
 export async function getPostBySlug(slug: string) {
-  const data = await fetch(`/api/posts/${slug}`)
+  const data = await fetch(`https://api.vercel.app/posts/${slug}`)
   return data.json()
 }
 ```

From b6cf0a1d02c93eba7038699360d1d97ef3a7962b Mon Sep 17 00:00:00 2001
From: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Date: Tue, 17 Dec 2024 10:13:34 +0000
Subject: [PATCH 16/25] Update
 docs/01-app/01-getting-started/07-caching-and-revalidating.mdx

Co-authored-by: Lee Robinson <me@leerob.io>
---
 docs/01-app/01-getting-started/07-caching-and-revalidating.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
index 87a4131e643bc..33288533bee29 100644
--- a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
+++ b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
@@ -127,7 +127,7 @@ export async function getPosts(slug) {
 }
 ```
 
-With the approach above, you can call the function throughout your application code and the same cache entry will be reused as long as the arguments are the same.
+You can then call the function throughout your application code and the same cache entry will be reused, as long as the arguments to the function (e.g. `slug`) are the same.
 
 Alternatively, you can also cache all functions within a file by adding the `'use cache'` directive at the top of the file:
 

From eebe58c885e47f55670c8b467d3ff10cc20479f7 Mon Sep 17 00:00:00 2001
From: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Date: Tue, 17 Dec 2024 10:14:11 +0000
Subject: [PATCH 17/25] Clarify that functions within a file are cached
 separately

---
 .../01-app/01-getting-started/07-caching-and-revalidating.mdx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
index 604bc60491f92..a45107440452a 100644
--- a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
+++ b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
@@ -61,7 +61,7 @@ export default async function Page() {
 }
 ```
 
-Alternatively, you can add the `'use cache'` directive at the top of the file to mark all components in the file as cacheable:
+Alternatively, you can add the `'use cache'` directive at the top of the file to mark all components in the file as cacheable. Each component will be cached separately, with its own cache key.
 
 ```tsx filename="app/blog/page.tsx" highlight={1} switcher
 'use cache'
@@ -129,7 +129,7 @@ export async function getPosts(slug) {
 
 With the approach above, you can call the function throughout your application code and the same cache entry will be reused as long as the arguments are the same.
 
-Alternatively, you can also cache all functions within a file by adding the `'use cache'` directive at the top of the file:
+Alternatively, you can also cache all functions within a file by adding the `'use cache'` directive at the top of the file. Each function will be cached separately, with its own cache key.
 
 ```ts filename="app/lib/data.ts" switcher
 'use cache'

From 6d9cd977c742b67952d36d9d44df85b5b51382f2 Mon Sep 17 00:00:00 2001
From: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Date: Tue, 17 Dec 2024 10:15:35 +0000
Subject: [PATCH 18/25] Update
 docs/01-app/01-getting-started/07-caching-and-revalidating.mdx

Co-authored-by: Lee Robinson <me@leerob.io>
---
 docs/01-app/01-getting-started/07-caching-and-revalidating.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
index 33288533bee29..6da538751345c 100644
--- a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
+++ b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
@@ -161,7 +161,7 @@ export async function getPostBySlug(slug: string) {
 
 ## Revalidating
 
-Revalidation allows you to update cached content without having to rebuild your entire application. It's useful for content that _sometimes_ changes, but would benefit from being cached to improve your application'sperformance.
+Revalidation allows you to update cached content without having to rebuild your entire application. It's useful for content that _sometimes_ changes, but would benefit from being cached to improve your application's performance.
 
 In Next.js, there are two types of revalidation:
 

From f5a83428306601f71d666c97cbbd7e17fcfc029d Mon Sep 17 00:00:00 2001
From: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Date: Tue, 17 Dec 2024 10:41:25 +0000
Subject: [PATCH 19/25] Clean up

---
 .../01-getting-started/07-caching-and-revalidating.mdx      | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
index 2372380b57e72..a607044b8e81b 100644
--- a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
+++ b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
@@ -61,7 +61,7 @@ export default async function Page() {
 }
 ```
 
-Alternatively, you can add the `'use cache'` directive at the top of the file to mark all components in the file as cacheable. Each component will be cached separately, with its own cache key.
+Alternatively, you can add the `'use cache'` directive at the top of the file to mark all components in the file as cacheable. Each component will be cached separately, with its own [cache key](/docs/app/api-reference/directives/use-cache#cache-keys).
 
 ```tsx filename="app/blog/page.tsx" highlight={1} switcher
 'use cache'
@@ -127,9 +127,9 @@ export async function getPosts(slug) {
 }
 ```
 
-You can then call the function throughout your application code and the same cache entry will be reused, as long as the arguments to the function (e.g. `slug`) are the same.
+You can then call the function throughout your application code and the same cache entry will be reused, as long as the arguments to the function (e.g. `slug`) are the same. If the arguments are different, a new cache key will be created for the new arguments.
 
-Alternatively, you can also cache all functions within a file by adding the `'use cache'` directive at the top of the file. Each function will be cached separately, with its own cache key.
+Alternatively, you can also cache all functions within a file by adding the `'use cache'` directive at the top of the file. Each function will be cached separately.
 
 ```ts filename="app/lib/data.ts" switcher
 'use cache'

From 89db02d95daed343c98baedf2dc8d7d5fbe873d2 Mon Sep 17 00:00:00 2001
From: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Date: Tue, 17 Dec 2024 10:50:21 +0000
Subject: [PATCH 20/25] clean up

---
 .../01-app/01-getting-started/07-caching-and-revalidating.mdx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
index a607044b8e81b..ea2f17698ae1b 100644
--- a/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
+++ b/docs/01-app/01-getting-started/07-caching-and-revalidating.mdx
@@ -61,7 +61,7 @@ export default async function Page() {
 }
 ```
 
-Alternatively, you can add the `'use cache'` directive at the top of the file to mark all components in the file as cacheable. Each component will be cached separately, with its own [cache key](/docs/app/api-reference/directives/use-cache#cache-keys).
+Alternatively, you can add the `'use cache'` directive at the top of the file to mark all components in the file as cacheable. Each component will be cached separately, with its own cache key.
 
 ```tsx filename="app/blog/page.tsx" highlight={1} switcher
 'use cache'
@@ -177,7 +177,7 @@ You can use the [`cacheLife` function](/docs/app/api-reference/functions/cacheLi
 To use `cacheLife`, import it from `next/cache` and nest it within the **scope** of the `'use cache'` directive and the function. For example, to revalidate the blog page after one hour:
 
 ```tsx filename="app/blog/page.tsx" highlight={3,6} switcher
-'use cache'o/>:.
+'use cache'
 
 import { cacheLife } from 'next/cache'
 

From c839e797c29eb46a474cfe3673febb2fa8be137d Mon Sep 17 00:00:00 2001
From: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Date: Tue, 4 Mar 2025 13:47:01 +0000
Subject: [PATCH 21/25] Add "How `use cache` works" section

---
 .../01-directives/use-cache.mdx               | 67 ++++++++++++++-----
 1 file changed, 52 insertions(+), 15 deletions(-)

diff --git a/docs/01-app/04-api-reference/01-directives/use-cache.mdx b/docs/01-app/04-api-reference/01-directives/use-cache.mdx
index 651342e9e3e50..b5eaa8d0566c5 100644
--- a/docs/01-app/04-api-reference/01-directives/use-cache.mdx
+++ b/docs/01-app/04-api-reference/01-directives/use-cache.mdx
@@ -14,11 +14,11 @@ related:
     - app/api-reference/functions/revalidateTag
 ---
 
-The `use cache` directive designates a component and/or a function to be cached. It can be used at the top of a file to indicate that all exports in the file are cacheable, or inline at the top of a function or component to inform Next.js the return value should be cached and reused for subsequent requests. This is an experimental Next.js feature, and not a native React feature like [`use client`](/docs/app/api-reference/directives/use-client) or [`use server`](/docs/app/api-reference/directives/use-server).
+The `use cache` directive allows you to mark a component or a function as cacheable. It can be used at the top of a file to indicate that all exports in the file should be cached, or inline at the top of function or component to cache the return value.
 
 ## Usage
 
-Enable support for the `use cache` directive with the [`useCache`](/docs/app/api-reference/config/next-config-js/useCache) flag in your `next.config.ts` file:
+`use cache` is currently an experimental feature. To enable it, add the [`useCache`](/docs/app/api-reference/config/next-config-js/useCache) option to your `next.config.ts` file:
 
 ```ts filename="next.config.ts" switcher
 import type { NextConfig } from 'next'
@@ -43,9 +43,9 @@ const nextConfig = {
 module.exports = nextConfig
 ```
 
-Additionally, `use cache` directives are also enabled when the [`dynamicIO`](/docs/app/api-reference/config/next-config-js/dynamicIO) flag is set.
+> `use cache` can also be enabled with the [`dynamicIO`](/docs/app/api-reference/config/next-config-js/dynamicIO) option.
 
-Then, you can use the `use cache` directive at the file, component, or function level:
+Then, add `use cache` at the file, component, or function level:
 
 ```tsx
 // File level
@@ -69,16 +69,53 @@ export async function getData() {
 }
 ```
 
-## Good to know
+Functions that use the `use cache` directive must not have any side-effects, such as modifying state, directly manipulating the DOM, or setting timers to execute code at intervals.
 
-- `use cache` is an experimental Next.js feature, and not a native React feature like [`use client`](/docs/app/api-reference/directives/use-client) or [`use server`](/docs/app/api-reference/directives/use-server).
-- Any [serializable](https://react.dev/reference/rsc/use-server#serializable-parameters-and-return-values) arguments (or props) passed to the cached function, as well as any serializable values it reads from the parent scope, will be converted to a format like JSON and automatically become a part of the cache key.
-- Any non-serializable arguments, props, or closed-over values will turn into opaque references inside the cached function, and can be only passed through and not inspected nor modified. These non-serializable values will be filled in at the request time and won't become a part of the cache key.
-  - For example, a cached function can take in JSX as a `children` prop and return `<div>{children}</div>`, but it won't be able to introspect the actual `children` object.
-- The return value of the cacheable function must also be serializable. This ensures that the cached data can be stored and retrieved correctly.
-- Functions that use the `use cache` directive must not have any side-effects, such as modifying state, directly manipulating the DOM, or setting timers to execute code at intervals.
-- If used alongside [Partial Prerendering](/docs/app/building-your-application/rendering/partial-prerendering), segments that have `use cache` will be prerendered as part of the static HTML shell.
-- Unlike [`unstable_cache`](/docs/app/api-reference/functions/unstable_cache) which only supports JSON data, `use cache` can cache any serializable data React can render, including the render output of components.
+## How `use cache` works
+
+### Cache keys
+
+`use cache` creates a cache entry, the key of which is generated using the following:
+
+- Build ID (generated for each build)
+- Function ID (a secure identifier unique to the function)
+- The [serializable](https://react.dev/reference/rsc/use-server#serializable-parameters-and-return-values) function arguments (or props).
+
+The arguments passed to the cached function, as well as any values it reads from the parent scope, are converted to a format like JSON and automatically become a part of the key. This means, the same cache entry will be reused as long as the arguments passed to the function are the same.
+
+## Non-serializable arguments
+
+Any non-serializable arguments, props, or closed-over values will turn into opaque references inside the cached function, and can be only passed through and not inspected nor modified. These non-serializable values will be filled in at the request time and won't become a part of the cache key.
+
+For example, a cached function can take in JSX as a `children` prop and return `<div>{children}</div>`, but it won't be able to introspect the actual `children` object.
+
+```tsx filename="app/ui/cached-component.tsx" switcher
+function CachedComponent({ children }: { children: ReactNode }) {
+  'use cache'
+  return <div>{children}</div>
+}
+```
+
+```jsx filename="app/ui/cached-component.js" switcher
+function CachedComponent({ children }) {
+  'use cache'
+  return <div>{children}</div>
+}
+```
+
+## Return values
+
+The return value of the cacheable function must be serializable. This ensures that the cached data can be stored and retrieved correctly.
+
+## At build time or during revalidation
+
+When used at the top of a [layout](/docs/app/api-reference/file-conventions/layout) or [page](/docs/app/api-reference/file-conventions/page), the route segment will be prerendered, allowing it to later be revalidated with the [`cacheTag`](/docs/app/api-reference/functions/cacheTag) and [`cacheLife`](/docs/app/api-reference/functions/cacheLife) APIs.
+
+This means `use cache` cannot be used with [request-time APIs](/docs/app/building-your-application/rendering/server-components#dynamic-apis) like `cookies` or `headers`.
+
+## At runtime
+
+During runtime, the `use cache` entries will be cached in-memory for the duration of the server request. Then, on the client, any content returned from the server will be cached in the browser's memory for the duration... TODO
 
 ## Examples
 
@@ -140,9 +177,9 @@ export default function Page() {
 
 > This is recommended for applications that previously used the [`export const dynamic = "force-static"`](/docs/app/api-reference/file-conventions/route-segment-config#dynamic) option, and will ensure the entire route is prerendered.
 
-### Caching component output with `use cache`
+### Caching a component's output with `use cache`
 
-You can use `use cache` at the component level to cache any fetches or computations performed within that component. When you reuse the component throughout your application it can share the same cache entry as long as the props maintain the same structure.
+You can use `use cache` at the component level to cache any fetches or computations performed within that component. When you reuse the component throughout your application it can share the same cache entry as long as the props are the same (see [Cache Keys](#cache-keys)).
 
 The props are serialized and form part of the cache key, and the cache entry will be reused as long as the serialized props produce the same value in each instance.
 

From 8d9e017cf265fd2a9f347156dde6afbd15e61b7f Mon Sep 17 00:00:00 2001
From: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Date: Tue, 4 Mar 2025 14:15:41 +0000
Subject: [PATCH 22/25] Move revalidation section up

---
 .../01-directives/use-cache.mdx               | 30 +++++++++----------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/docs/01-app/04-api-reference/01-directives/use-cache.mdx b/docs/01-app/04-api-reference/01-directives/use-cache.mdx
index b5eaa8d0566c5..3f279498cd76a 100644
--- a/docs/01-app/04-api-reference/01-directives/use-cache.mdx
+++ b/docs/01-app/04-api-reference/01-directives/use-cache.mdx
@@ -107,9 +107,9 @@ function CachedComponent({ children }) {
 
 The return value of the cacheable function must be serializable. This ensures that the cached data can be stored and retrieved correctly.
 
-## At build time or during revalidation
+## At build time
 
-When used at the top of a [layout](/docs/app/api-reference/file-conventions/layout) or [page](/docs/app/api-reference/file-conventions/page), the route segment will be prerendered, allowing it to later be revalidated with the [`cacheTag`](/docs/app/api-reference/functions/cacheTag) and [`cacheLife`](/docs/app/api-reference/functions/cacheLife) APIs.
+When used at the top of a [layout](/docs/app/api-reference/file-conventions/layout) or [page](/docs/app/api-reference/file-conventions/page), the route segment will be prerendered, allowing it to later be [revalidated](#during-revalidation).
 
 This means `use cache` cannot be used with [request-time APIs](/docs/app/building-your-application/rendering/server-components#dynamic-apis) like `cookies` or `headers`.
 
@@ -117,6 +117,19 @@ This means `use cache` cannot be used with [request-time APIs](/docs/app/buildin
 
 During runtime, the `use cache` entries will be cached in-memory for the duration of the server request. Then, on the client, any content returned from the server will be cached in the browser's memory for the duration... TODO
 
+## During revalidation
+
+By default, Next.js sets a **[revalidation period](/docs/app/building-your-application/data-fetching/fetching#revalidating-cached-data) of 15 minutes** when you use the `use cache` directive, and anear-infinite expiration duration, meaning it's suitable for content that doesn't need frequent updates.
+
+While this revalidation period may be useful for content you don't expect to change often, you can use the `cacheLife` and `cacheTag` APIs to configure when the individual cache entries should be revalidated.
+
+- [`cacheLife`](/docs/app/api-reference/functions/cacheLife): For time-based revalidation periods.
+- [`cacheTag`](/docs/app/api-reference/functions/cacheTag): For on-demand revalidation.
+
+Both of these APIs integrate across the client and server caching layers, meaning you can configure your caching semantics in one place and have them apply everywhere.
+
+See the [`cacheLife`](/docs/app/api-reference/functions/cacheLife) and [`cacheTag`](/docs/app/api-reference/functions/cacheTag) API docs for more information.
+
 ## Examples
 
 ### Caching an entire route with `use cache`
@@ -231,19 +244,6 @@ export async function getData() {
 }
 ```
 
-### Revalidating
-
-By default, Next.js sets a **[revalidation period](/docs/app/building-your-application/data-fetching/fetching#revalidating-cached-data) of 15 minutes** when you use the `use cache` directive. Next.js sets a near-infinite expiration duration, meaning it's suitable for content that doesn't need frequent updates.
-
-While this revalidation period may be useful for content you don't expect to change often, you can use the `cacheLife` and `cacheTag` APIs to configure the cache behavior:
-
-- [`cacheLife`](/docs/app/api-reference/functions/cacheLife): For time-based revalidation periods.
-- [`cacheTag`](/docs/app/api-reference/functions/cacheTag): For on-demand revalidation.
-
-Both of these APIs integrate across the client and server caching layers, meaning you can configure your caching semantics in one place and have them apply everywhere.
-
-See the [`cacheLife`](/docs/app/api-reference/functions/cacheLife) and [`cacheTag`](/docs/app/api-reference/functions/cacheTag) docs for more information.
-
 ### Interleaving
 
 If you need to pass non-serializable arguments to a cacheable function, you can pass them as `children`. This means the `children` reference can change without affecting the cache entry.

From 66559c9fba922d3e6f72e3311333133fbdf0b9f9 Mon Sep 17 00:00:00 2001
From: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Date: Tue, 4 Mar 2025 14:18:15 +0000
Subject: [PATCH 23/25] Remove repetition

---
 docs/01-app/04-api-reference/01-directives/use-cache.mdx | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/docs/01-app/04-api-reference/01-directives/use-cache.mdx b/docs/01-app/04-api-reference/01-directives/use-cache.mdx
index 3f279498cd76a..7d4f084d74456 100644
--- a/docs/01-app/04-api-reference/01-directives/use-cache.mdx
+++ b/docs/01-app/04-api-reference/01-directives/use-cache.mdx
@@ -192,9 +192,7 @@ export default function Page() {
 
 ### Caching a component's output with `use cache`
 
-You can use `use cache` at the component level to cache any fetches or computations performed within that component. When you reuse the component throughout your application it can share the same cache entry as long as the props are the same (see [Cache Keys](#cache-keys)).
-
-The props are serialized and form part of the cache key, and the cache entry will be reused as long as the serialized props produce the same value in each instance.
+You can use `use cache` at the component level to cache any fetches or computations performed within that component. The cache entry will be reused as long as the serialized props produce the same value in each instance.
 
 ```tsx filename="app/components/bookings.tsx" highlight={2} switcher
 export async function Bookings({ type = 'haircut' }: BookingsProps) {
@@ -224,7 +222,7 @@ export async function Bookings({ type = 'haircut' }) {
 
 ### Caching function output with `use cache`
 
-Since you can add `use cache` to any asynchronous function, you aren't limited to caching components or routes only. You might want to cache a network request or database query or compute something that is very slow. By adding `use cache` to a function containing this type of work it becomes cacheable, and when reused, will share the same cache entry.
+Since you can add `use cache` to any asynchronous function, you aren't limited to caching components or routes only. You might want to cache a network request, a database query, or a slow computation.
 
 ```tsx filename="app/actions.ts" highlight={2} switcher
 export async function getData() {

From 03e4bc7ad6f4aca9f977a9548e9eb8310c1694f6 Mon Sep 17 00:00:00 2001
From: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Date: Tue, 4 Mar 2025 14:21:04 +0000
Subject: [PATCH 24/25] Clean up

---
 docs/01-app/04-api-reference/01-directives/use-cache.mdx | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/docs/01-app/04-api-reference/01-directives/use-cache.mdx b/docs/01-app/04-api-reference/01-directives/use-cache.mdx
index 7d4f084d74456..58e5dac20b923 100644
--- a/docs/01-app/04-api-reference/01-directives/use-cache.mdx
+++ b/docs/01-app/04-api-reference/01-directives/use-cache.mdx
@@ -115,13 +115,15 @@ This means `use cache` cannot be used with [request-time APIs](/docs/app/buildin
 
 ## At runtime
 
-During runtime, the `use cache` entries will be cached in-memory for the duration of the server request. Then, on the client, any content returned from the server will be cached in the browser's memory for the duration... TODO
+During runtime, the `use cache` entries will be cached in-memory for the duration of the server request.
+
+Then, on the client, any content returned from the server will be cached in the browser's memory for the duration of browser session or until [revalidated](#during-revalidation).
 
 ## During revalidation
 
-By default, Next.js sets a **[revalidation period](/docs/app/building-your-application/data-fetching/fetching#revalidating-cached-data) of 15 minutes** when you use the `use cache` directive, and anear-infinite expiration duration, meaning it's suitable for content that doesn't need frequent updates.
+By default, Next.js sets a revalidation period of **15 minutes** when you use the `use cache` directive, and a near-infinite expiration duration.
 
-While this revalidation period may be useful for content you don't expect to change often, you can use the `cacheLife` and `cacheTag` APIs to configure when the individual cache entries should be revalidated.
+While this revalidation period may be useful for content that doesn't require frequent updates, you can use the `cacheLife` and `cacheTag` APIs to configure when the individual cache entries should be revalidated.
 
 - [`cacheLife`](/docs/app/api-reference/functions/cacheLife): For time-based revalidation periods.
 - [`cacheTag`](/docs/app/api-reference/functions/cacheTag): For on-demand revalidation.

From 4b2892e816d5ff3d413057c3ddc7aa764ced497a Mon Sep 17 00:00:00 2001
From: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Date: Tue, 4 Mar 2025 14:36:06 +0000
Subject: [PATCH 25/25] grammar

---
 docs/01-app/04-api-reference/01-directives/use-cache.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/01-app/04-api-reference/01-directives/use-cache.mdx b/docs/01-app/04-api-reference/01-directives/use-cache.mdx
index 58e5dac20b923..bd16c95063b9e 100644
--- a/docs/01-app/04-api-reference/01-directives/use-cache.mdx
+++ b/docs/01-app/04-api-reference/01-directives/use-cache.mdx
@@ -117,7 +117,7 @@ This means `use cache` cannot be used with [request-time APIs](/docs/app/buildin
 
 During runtime, the `use cache` entries will be cached in-memory for the duration of the server request.
 
-Then, on the client, any content returned from the server will be cached in the browser's memory for the duration of browser session or until [revalidated](#during-revalidation).
+Then, on the client, any content returned from the server will be cached in the browser's memory for the duration of the session or until [revalidated](#during-revalidation).
 
 ## During revalidation