Unverified Commit 5c589abd authored by Jinsoo Lee's avatar Jinsoo Lee Committed by GitHub

docs: document cacheLife expire omission behavior and fix default preset value (#89913)

## Summary
- Add note that omitting `expire` in `cacheLife` results in cache never
expiring
- Fix `default` preset table: `expire` was documented as "1 year" but
actual code uses `INFINITE_CACHE` (never)
- Add mention of expire omission behavior in custom profiles section

## Why
The `expire` property is optional (`expire?: number`), but the
documentation didn't explain
what happens when it's omitted. The source code shows it defaults to
`INFINITE_CACHE` (0xfffffffe),
meaning the cache never expires. Additionally, the preset profile table
incorrectly listed
the `default` profile's expire as "1 year" when the actual value is
`INFINITE_CACHE`.

### Source code references
- `packages/next/src/lib/constants.ts:45` — `INFINITE_CACHE =
0xfffffffe`
- `packages/next/src/server/config-shared.ts:1580` — `default.expire:
INFINITE_CACHE`
- `packages/next/src/server/use-cache/cache-life.ts:156` — only sets
`explicitExpire` when `expire !== undefined`
- `packages/next/src/server/use-cache/use-cache-wrapper.ts:477-479` —
falls back to `defaultCacheLife.expire` (INFINITE_CACHE)

---------
Co-authored-by: 's avatarJoseph <joseph.chamochumbi@vercel.com>
parent 9e4e6d6f
...@@ -93,6 +93,8 @@ Cache profiles control caching behavior through three timing properties: ...@@ -93,6 +93,8 @@ Cache profiles control caching behavior through three timing properties:
During this time, the client-side router displays cached content immediately without any network request. After this period expires, the router must check with the server on the next navigation or request. This provides instant page loads from the client cache, but data may be outdated. During this time, the client-side router displays cached content immediately without any network request. After this period expires, the router must check with the server on the next navigation or request. This provides instant page loads from the client cache, but data may be outdated.
- If omitted, defaults to the `default` profile's `stale` value (5 minutes, see [`staleTimes`](/docs/app/api-reference/config/next-config-js/staleTimes))
```tsx ```tsx
cacheLife({ stale: 300 }) // 5 minutes cacheLife({ stale: 300 }) // 5 minutes
``` ```
...@@ -106,6 +108,7 @@ How often the server regenerates cached content in the background. ...@@ -106,6 +108,7 @@ How often the server regenerates cached content in the background.
2. Regenerates content in the background 2. Regenerates content in the background
3. Updates the cache with fresh content 3. Updates the cache with fresh content
- Similar to [Incremental Static Regeneration (ISR)](/docs/app/guides/incremental-static-regeneration) - Similar to [Incremental Static Regeneration (ISR)](/docs/app/guides/incremental-static-regeneration)
- If omitted, defaults to the `default` profile's `revalidate` value (15 minutes)
```tsx ```tsx
cacheLife({ revalidate: 900 }) // 15 minutes cacheLife({ revalidate: 900 }) // 15 minutes
...@@ -117,6 +120,7 @@ Maximum time before the server must regenerate cached content. ...@@ -117,6 +120,7 @@ Maximum time before the server must regenerate cached content.
- After this period with no traffic, the server regenerates content synchronously on the next request - After this period with no traffic, the server regenerates content synchronously on the next request
- When you set both `revalidate` and `expire`, `expire` must be longer than `revalidate`. Next.js validates this and raises an error for invalid configurations. - When you set both `revalidate` and `expire`, `expire` must be longer than `revalidate`. Next.js validates this and raises an error for invalid configurations.
- If omitted, defaults to the `default` profile's `expire` value (never expires)
```tsx ```tsx
cacheLife({ expire: 3600 }) // 1 hour cacheLife({ expire: 3600 }) // 1 hour
...@@ -128,7 +132,7 @@ If you don't specify a profile, Next.js uses the `default` profile. We recommend ...@@ -128,7 +132,7 @@ If you don't specify a profile, Next.js uses the `default` profile. We recommend
| **Profile** | **Use Case** | `stale` | `revalidate` | `expire` | | **Profile** | **Use Case** | `stale` | `revalidate` | `expire` |
| ----------- | -------------------------------------- | ---------- | ------------ | -------- | | ----------- | -------------------------------------- | ---------- | ------------ | -------- |
| `default` | Standard content | 5 minutes | 15 minutes | 1 year | | `default` | Standard content | 5 minutes | 15 minutes | never |
| `seconds` | Real-time data | 30 seconds | 1 second | 1 minute | | `seconds` | Real-time data | 30 seconds | 1 second | 1 minute |
| `minutes` | Frequently updated content | 5 minutes | 1 minute | 1 hour | | `minutes` | Frequently updated content | 5 minutes | 1 minute | 1 hour |
| `hours` | Content updated multiple times per day | 5 minutes | 1 hour | 1 day | | `hours` | Content updated multiple times per day | 5 minutes | 1 hour | 1 day |
...@@ -174,6 +178,8 @@ module.exports = nextConfig ...@@ -174,6 +178,8 @@ module.exports = nextConfig
The example above caches for 14 days, checks for updates daily, and expires the cache after 14 days. You can then reference this profile throughout your application by its name: The example above caches for 14 days, checks for updates daily, and expires the cache after 14 days. You can then reference this profile throughout your application by its name:
> **Good to know**: Any omitted properties in a custom profile inherit from the `default` profile. This also applies to inline profile objects passed directly to `cacheLife()`.
```tsx filename="app/page.tsx" highlight={5} ```tsx filename="app/page.tsx" highlight={5}
'use cache' 'use cache'
import { cacheLife } from 'next/cache' import { cacheLife } from 'next/cache'
...@@ -552,7 +558,7 @@ This pattern is useful when different outcomes need different cache durations, f ...@@ -552,7 +558,7 @@ This pattern is useful when different outcomes need different cache durations, f
If you want to calculate cache lifetime at runtime, for example by reading it from the fetched data, use an [inline cache profile](#inline-cache-profiles) object: If you want to calculate cache lifetime at runtime, for example by reading it from the fetched data, use an [inline cache profile](#inline-cache-profiles) object:
```tsx filename="lib/posts.ts" highlight={15,16,17} ```tsx filename="lib/posts.ts" highlight={15,16,17,18}
import { cacheLife, cacheTag } from 'next/cache' import { cacheLife, cacheTag } from 'next/cache'
async function getPostContent(slug: string) { async function getPostContent(slug: string) {
...@@ -569,6 +575,7 @@ async function getPostContent(slug: string) { ...@@ -569,6 +575,7 @@ async function getPostContent(slug: string) {
// Use cache timing from CMS data directly as an object // Use cache timing from CMS data directly as an object
cacheLife({ cacheLife({
// Ensure post.revalidateSeconds is a number in seconds // Ensure post.revalidateSeconds is a number in seconds
// stale and expire inherit from 'default' profile
revalidate: post.revalidateSeconds ?? 3600, revalidate: post.revalidateSeconds ?? 3600,
}) })
......
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