cacheLife in Next.js — Controlling Cache Duration for Components and Functions

1. What Is cacheLife?

cacheLife is a function in Next.js that defines how long a component or function should be cached. It must be used with the 'use cache' directive and placed inside the same scope.

2. Initial Setup

To use cacheLife, enable cacheComponents in your next.config.ts:

const nextConfig = {
  cacheComponents: true,
}
export default nextConfig

3. Preset Cache Profiles

Next.js offers built-in cache profiles:

Profile	Use Case	stale	revalidate	expire
seconds	Real-time data	30s	1s	1m
minutes	Frequently updated	5m	1m	1h
hours	Updated multiple times daily	5m	1h	1d
days	Daily updates	5m	1d	1w
weeks	Weekly updates	5m	1w	30d
max	Stable content	5m	30d	1y

4. Understanding stale, revalidate, expire

• stale: How long the client can use cached data without checking the server
• revalidate: After this time, the server refreshes the cache in the background
• expire: After this time with no traffic, the server regenerates content synchronously

5. Using a Preset Profile

// app/blog/page.tsx
'use cache'
import { cacheLife } from 'next/cache'

export default async function BlogPage() {
  cacheLife('days') // Blog content updates daily
  const posts = await getBlogPosts()
  return <div>{posts}</div>
}

6. Defining Custom Profiles

// next.config.ts
const nextConfig = {
  cacheComponents: true,
  cacheLife: {
    editorial: {
      stale: 600, // 10 minutes
      revalidate: 3600, // 1 hour
      expire: 86400, // 1 day
    },
  },
}
export default nextConfig

7. Using a Custom Profile

// app/editorial/page.tsx
'use cache'
import { cacheLife } from 'next/cache'

export default async function EditorialPage() {
  cacheLife('editorial')
  // ...
}

8. Inline Profiles

// app/page.tsx
'use cache'
import { cacheLife } from 'next/cache'

export default async function Page() {
  cacheLife({
    stale: 3600,
    revalidate: 900,
    expire: 86400,
  })
  return <div>Page</div>
}

9. Client Router Behavior

The stale value affects the client-side router cache, not the Cache-Control header. It’s sent via the x-nextjs-stale-time response header and helps the router decide when to revalidate.

10. Advanced Examples

• Product page with hourly cache: cacheLife('hours')
• Real-time widget with second-level cache: cacheLife('seconds')
• Stable settings function: cacheLife('max')

Conclusion

The cacheLife function in Next.js gives you precise control over caching behavior at the component or function level. Whether using presets or custom profiles, it helps optimize performance and freshness across your app.