docs: document cacheLife expire omission behavior and fix default preset value

[01-binary]

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)

[nextjs-bot]

Allow CI Workflow Run

• approve CI run for commit: a90e729

Note: this should only be enabled once the PR is ready to go and can only be enabled by a maintainer

[icyJoseph]

I had a bit of back and fort here, because 1 year expire time, in practical terms is negligible - aka, I chose to focus on intent (given that this effectively means, no visits at all, for one 1 year) Did you have an actual problem at runtime? Did you see max and default as equals in that dimension?

[icyJoseph]

Ok, I think we'll do like this, 🙏 - I think there's a slightly bigger problem here:

1. Keep the table change
2. Let's add a bullet point to all three properties (~ line 98, 112, 123 approx)

• If omitted, defaults to "default" profile's stale value (5 minutes, see /docs/app/api-reference/config/next-config-js/staleTimes)

• If omitted, defaults to the default profile's revalidate value (15 minutes).

• If omitted, defaults to the default profile's expire value (never expires).

3. Instead of If you omit expire, the cache will never expire, similar to the default profile., add this right after the snippet

> **Good to know**: Any omitted properties in a custom profile inherit from the `default` profile.

Maybe should also say: This also applies to inline profile objects passed directly to cacheLife().

4. Way later at line 570-ish

  cacheLife({
    // Ensure post.revalidateSeconds is a number in seconds
    // stale and expire inherit from 'default' profile
    revalidate: post.revalidateSeconds ?? 3600,
  })

Let's reinforce this idea. Make sure the highlight is still correct

---

Thanks for the PR!

[01-binary]

I had a bit of back and fort here, because 1 year expire time, in practical terms is negligible - aka, I chose to focus on intent (given that this effectively means, no visits at all, for one 1 year) Did you have an actual problem at runtime? Did you see max and default as equals in that dimension?

No, I didn't encounter an actual runtime issue — this came from reading the source code to understand the cacheLife API.

The main thing that caught my attention was that the docs listed both default and max as "1 year" for expire, which made them appear identical in that dimension. But looking at the code, default uses INFINITE_CACHE while max uses 606024*365, so they're intentionally different values. I completely agree that the practical difference is negligible, but I thought aligning the docs with the actual code would help avoid confusion for anyone reading both.

That said, the bigger motivation was that the docs didn't mention what happens when expire is omitted entirely — which I think is useful for users defining custom or inline profiles.

Thank you for the detailed feedback — I'll update the PR accordingly!

[01-binary]

I've updated the PR with all the requested changes!