Unverified Commit 5b243a2d authored by Delba de Oliveira's avatar Delba de Oliveira Committed by GitHub

Docs: Improve `"use cache"` and `cacheLife` API references (#78024)

Decoupling from: https://github.com/vercel/next.js/pull/73437


- Add "How `use cache` works" section
  - Clarify cache keys inputs
  - Describe what happens during build, runtime, and revalidation
- Correct the default values for the `cacheLife` profiles
- Add the default time for `expireTime`
- Add note about `staleTimes` and `expireTime` affecting the default
cache profile
parent 717e54b0
...@@ -66,22 +66,24 @@ export default async function Page() { ...@@ -66,22 +66,24 @@ export default async function Page() {
### Default cache profiles ### Default cache profiles
Next.js provides a set of named cache profiles modeled on various timescales. If you don't specify a cache profile in the `cacheLife` function alongside the `use cache` directive, Next.js will automatically apply the “default” cache profile. Next.js provides a set of named cache profiles modeled on various timescales. If you don't specify a cache profile in the `cacheLife` function alongside the `use cache` directive, Next.js will automatically apply the `default` cache profile.
However, we recommend always adding a cache profile when using the `use cache` directive to explicitly define caching behavior. However, we recommend always adding a cache profile when using the `use cache` directive to explicitly define caching behavior.
| **Profile** | **Stale** | **Revalidate** | **Expire** | **Description** | | **Profile** | `stale` | `revalidate` | `expire` | **Description** |
| ----------- | --------- | -------------- | -------------- | ------------------------------------------------------------------------ | | ----------- | --------- | ------------ | -------- | ------------------------------------------------------------------------ |
| `default` | undefined | 15 minutes | INFINITE_CACHE | Default profile, suitable for content that doesn't need frequent updates | | `default` | 5 minutes | 15 minutes | 1 year | Default profile, suitable for content that doesn't need frequent updates |
| `seconds` | undefined | 1 second | 1 minute | For rapidly changing content requiring near real-time updates | | `seconds` | 0 | 1 second | 1 second | For rapidly changing content requiring near real-time updates |
| `minutes` | 5 minutes | 1 minute | 1 hour | For content that updates frequently within an hour | | `minutes` | 5 minutes | 1 minute | 1 hour | For content that updates frequently within an hour |
| `hours` | 5 minutes | 1 hour | 1 day | For content that updates daily but can be slightly stale | | `hours` | 5 minutes | 1 hour | 1 day | For content that updates daily but can be slightly stale |
| `days` | 5 minutes | 1 day | 1 week | For content that updates weekly but can be a day old | | `days` | 5 minutes | 1 day | 1 week | For content that updates weekly but can be a day old |
| `weeks` | 5 minutes | 1 week | 1 month | For content that updates monthly but can be a week old | | `weeks` | 5 minutes | 1 week | 30 days | For content that updates monthly but can be a week old |
| `max` | 5 minutes | 1 month | INFINITE_CACHE | For very stable content that rarely needs updating | | `max` | 5 minutes | 30 days | 1 year | For very stable content that rarely needs updating |
The string values used to reference cache profiles don't carry inherent meaning; instead they serve as semantic labels. This allows you to better understand and manage your cached content within your codebase. The string values used to reference cache profiles don't carry inherent meaning; instead they serve as semantic labels. This allows you to better understand and manage your cached content within your codebase.
> **Good to know:** Updating the [`staleTimes`](/docs/app/api-reference/config/next-config-js/staleTimes) and [`expireTime`](/docs/app/api-reference/config/next-config-js/expireTime) config options also updates the `stale` and `expire` properties of the `default` cache profile.
### Custom cache profiles ### Custom cache profiles
You can configure custom cache profiles by adding them to the [`cacheLife`](/docs/app/api-reference/config/next-config-js/cacheLife) option in your `next.config.ts` file. You can configure custom cache profiles by adding them to the [`cacheLife`](/docs/app/api-reference/config/next-config-js/cacheLife) option in your `next.config.ts` file.
......
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