Docs: Improve caching story

docs/01-app/01-getting-started/07-caching-and-revalidating.mdx

@@ -0,0 +1,299 @@
+---
+title: How to cache and revalidate components and functions
+nav_title: Caching and Revalidating
+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.
+  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
+    - 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.
+
+## Caching
+
+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 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.
+
+### 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:
+
+```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. Each component will be cached separately, with its own cache key.
+
+```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>
+  )
+}
+```
+
+### Functions
+
+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(`https://api.vercel.app/posts/${slug}`)
+  return data.json()
+}
+```
+
+```js filename="app/lib/data.js" switcher
+export async function getPosts(slug) {
+  'use cache'
+  const data = await fetch(`https://api.vercel.app/posts/${slug}`)
+  return data.json()
+}
+```
+
+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.
+
+```ts filename="app/lib/data.ts" switcher
+'use cache'
+
+export async function getPosts() {
+  const data = await fetch(`https://api.vercel.app/posts`)
+  return data.json()
+}
+
+export async function getPostBySlug(slug: string) {
+  const data = await fetch(`https://api.vercel.app/posts/${slug}`)
+  return data.json()
+}
+```
+
+```js filename="app/lib/data.js" switcher
+'use cache'
+
+export async function getPosts() {
+  const data = await fetch(`https://api.vercel.app/posts/`)
+  return data.json()
+}
+
+export async function getPostBySlug(slug: string) {
+  const data = await fetch(`https://api.vercel.app/posts/${slug}`)
+  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 your application's performance.
+
+In Next.js, there are two types of revalidation:
+
+- [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
+
+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'`. 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 the function. For example, to revalidate the blog page after 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} />
+}
+```
+
+## 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 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:
+
+```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 to create a new post, call `revalidateTag` using the same tag to purge the cache entry:
+
+```tsx filename="app/actions.ts" switcher
+'use server'
+
+import { revalidateTag } from 'next/cache'
+
+export async function createPost() {
+  // Mutate data
+  // ...
+
+  // Purge cache
+  revalidateTag('blog-posts')
+}
+```
+
+```jsx filename="app/actions.js" switcher
+'use server'
+
+import { revalidateTag } from 'next/cache'
+
+export async function createPost() {
+  // Mutate data
+  // ...
+
+  // Purge cache
+  revalidateTag('blog-posts')
+}
+```
+
+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 { revalidatePath } from 'next/cache'
+
+export async function createPost() {
+  // Mutate data
+  // ...
+
+  // Purge cache
+  revalidatePath('/blog')
+}
+```
+
+```tsx filename="app/actions.ts" switcher
+'use server'
+
+import { revalidatePath } from 'next/cache'
+
+export async function createPost() {
+  // Mutate data
+  // ...
+
+  // Purge cache
+  expirePath('/blog')
+}
+```