Next.js - cacheLife() Function

---

---

The cacheLife() Function

The Next.js cacheLife() function is used to set the cache lifetime for a function or component. It must be used alongside "use cache" directive, inside a function or component that you want to cache.

Syntax

Following is the syntax of cacheLife() function:

'use cache'
import { unstable_cacheLife as cacheLife } from 'next/cache'
 
export default async function Page() {
  cacheLife('hours')
  return <div>Page</div>
}

Parameters

The cacheLife() function takes a single parameter:

• timeUnit: A string representing the time unit for the cache lifetime. Possible values are 'seconds', 'minutes', 'hours', 'days', and 'weeks', corresponds to 1 second, 1 minute, 1 hour, 1 day, and 1 week respectively.

Return Value

The cacheLife() function does not return any value.

Enable cacheLife Function

The cacheLife function is an experimental feature in Next.js and needs to be enabled in the next.config.ts file. To enable the cacheLife function, set the experimental.dynamicIO flag to true in the next.config.ts file.

// File - next.config.ts

import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  experimental: {
    dynamicIO: true,
  },
}
 
export default nextConfig

Example 1

You can create a reusable cache profile by defining them in your next.config.ts file. Choose a name that suits your use case and set values for the stale, revalidate, and expire properties. You can create as many custom cache profiles as needed. Each profile can be referenced by its name as a string value passed to the cacheLife function

In the code below, we demonstrate how to set up a custom cache profile in next.config.ts and use it in a component.

// File - next.config.ts

import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  experimental: {
    dynamicIO: true,
    cacheLife: {
      biweekly: {
        stale: 60 * 60 * 24 * 14, // 14 days
        revalidate: 60 * 60 * 24, // 1 day
        expire: 60 * 60 * 24 * 14, // 14 days
      },
    },
  },
}
 
module.exports = nextConfig


// File -  app/page.tsx
'use cache'
import { unstable_cacheLife as cacheLife } from 'next/cache'
 
export default async function Page() {
  cacheLife('biweekly')
  return <div>Page</div>
}

Example 2

You can override the default named cache profiles by creating a new configuration with the same name as the defaults. In the code below, we demonstrate how to override the default cache profile in next.config.ts and use it in a component.

// File - next.config.ts

const nextConfig = {
    experimental: {
      dynamicIO: true,
      cacheLife: {
        days: {
          stale: 3600, // 1 hour
          revalidate: 900, // 15 minutes
          expire: 86400, // 1 day
        },
      },
    },
  }
   
  module.exports = nextConfig