Make cacheLife profiles configurable (#71232)

This should really be a global config but we don't have an easy way to
get the config from a module. Might need a loader. So this just plumbs
it through a bunch of contexts.

I'm also generate the enum type based on the config.

packages/next/cache.d.ts

@@ -4,3 +4,5 @@ export {
   revalidatePath,
 } from 'next/dist/server/web/spec-extension/revalidate'
 export { unstable_noStore } from 'next/dist/server/web/spec-extension/unstable-no-store'
+export { cacheLife as unstable_cacheLife } from 'next/dist/server/use-cache/cache-life'
+export { cacheTag as unstable_cacheTag } from 'next/dist/server/use-cache/cache-tag'

packages/next/cache.js

@@ -8,8 +8,9 @@ const cacheExports = {
   unstable_noStore:
     require('next/dist/server/web/spec-extension/unstable-no-store')
       .unstable_noStore,
-  unstable_cacheLife: require('next/dist/server/use-cache/cache-life'),
-  unstable_cacheTag: require('next/dist/server/use-cache/cache-tag'),
+  unstable_cacheLife: require('next/dist/server/use-cache/cache-life')
+    .cacheLife,
+  unstable_cacheTag: require('next/dist/server/use-cache/cache-tag').cacheTag,
 }
 
 // https://nodejs.org/api/esm.html#commonjs-namespaces
@@ -21,3 +22,5 @@ exports.unstable_cache = cacheExports.unstable_cache
 exports.revalidatePath = cacheExports.revalidatePath
 exports.revalidateTag = cacheExports.revalidateTag
 exports.unstable_noStore = cacheExports.unstable_noStore
+exports.unstable_cacheLife = cacheExports.unstable_cacheLife
+exports.unstable_cacheTag = cacheExports.unstable_cacheTag

packages/next/src/build/utils.ts

@@ -1217,6 +1217,7 @@ export async function buildAppStaticPaths({
   segments,
   isrFlushToDisk,
   cacheHandler,
+  cacheLifeProfiles,
   requestHeaders,
   maxMemoryCacheSize,
   fetchCacheKeyPrefix,
@@ -1235,6 +1236,9 @@ export async function buildAppStaticPaths({
   isrFlushToDisk?: boolean
   fetchCacheKeyPrefix?: string
   cacheHandler?: string
+  cacheLifeProfiles?: {
+    [profile: string]: import('../server/use-cache/cache-life').CacheLife
+  }
   maxMemoryCacheSize?: number
   requestHeaders: IncrementalCache['requestHeaders']
   nextConfigOutput: 'standalone' | 'export' | undefined
@@ -1305,6 +1309,7 @@ export async function buildAppStaticPaths({
       fallbackRouteParams: null,
       renderOpts: {
         incrementalCache,
+        cacheLifeProfiles,
         supportsDynamicResponse: true,
         isRevalidate: false,
         experimental: {
@@ -1489,6 +1494,7 @@ export async function isPageStatic({
   maxMemoryCacheSize,
   nextConfigOutput,
   cacheHandler,
+  cacheLifeProfiles,
   pprConfig,
   isAppPPRFallbacksEnabled,
   buildId,
@@ -1510,6 +1516,9 @@ export async function isPageStatic({
   isrFlushToDisk?: boolean
   maxMemoryCacheSize?: number
   cacheHandler?: string
+  cacheLifeProfiles?: {
+    [profile: string]: import('../server/use-cache/cache-life').CacheLife
+  }
   nextConfigOutput: 'standalone' | 'export' | undefined
   pprConfig: ExperimentalPPRConfig | undefined
   isAppPPRFallbacksEnabled: boolean | undefined
@@ -1632,6 +1641,7 @@ export async function isPageStatic({
               isrFlushToDisk,
               maxMemoryCacheSize,
               cacheHandler,
+              cacheLifeProfiles,
               ComponentMod,
               nextConfigOutput,
               isRoutePPREnabled,

packages/next/src/build/webpack-config.ts

@@ -1931,6 +1931,7 @@ export default async function getBaseWebpackConfig(
           isEdgeServer,
           pageExtensions: config.pageExtensions,
           typedRoutes: enableTypedRoutes,
+          cacheLifeConfig: config.experimental.cacheLife,
           originalRewrites,
           originalRedirects,
         }),

packages/next/src/build/webpack/plugins/next-types-plugin/index.test.ts

@@ -12,6 +12,7 @@ describe('next-types-plugin', () => {
       isEdgeServer: false,
       pageExtensions: ['tsx', 'ts', 'jsx', 'js'],
       typedRoutes: false,
+      cacheLifeConfig: undefined,
       originalRewrites: undefined,
       originalRedirects: undefined,
     })
@@ -40,6 +41,7 @@ describe('next-types-plugin', () => {
       isEdgeServer: false,
       pageExtensions: ['tsx', 'ts', 'jsx', 'js'],
       typedRoutes: false,
+      cacheLifeConfig: undefined,
       originalRewrites: undefined,
       originalRedirects: undefined,
     })
@@ -60,6 +62,7 @@ describe('next-types-plugin', () => {
       isEdgeServer: false,
       pageExtensions: ['tsx', 'ts', 'jsx', 'js'],
       typedRoutes: false,
+      cacheLifeConfig: undefined,
       originalRewrites: undefined,
       originalRedirects: undefined,
     })

packages/next/src/build/webpack/plugins/next-types-plugin/index.ts

@@ -17,6 +17,7 @@ import { getPageFromPath } from '../../../entries'
 import type { PageExtensions } from '../../../page-extensions-type'
 import { devPageFiles } from './shared'
 import { getProxiedPluginState } from '../../../build-context'
+import type { CacheLife } from '../../../../server/use-cache/cache-life'
 
 const PLUGIN_NAME = 'NextTypesPlugin'
 
@@ -34,6 +35,7 @@ interface Options {
   isEdgeServer: boolean
   pageExtensions: PageExtensions
   typedRoutes: boolean
+  cacheLifeConfig: undefined | { [profile: string]: CacheLife }
   originalRewrites: Rewrites | undefined
   originalRedirects: Redirect[] | undefined
 }
@@ -525,6 +527,40 @@ declare module 'next/form' {
 `
 }
 
+function createCustomCacheLifeDefinitions(cacheLife: {
+  [profile: string]: CacheLife
+}) {
+  const profiles = Object.keys(cacheLife)
+  if (!profiles.includes('default')) {
+    profiles.push('default')
+  }
+  for (let i = 0; i < profiles.length; i++) {
+    profiles[i] = JSON.stringify(profiles[i])
+  }
+
+  // TODO: Annotate each option with their expanded values for IDE support.
+  const profilesEnum = profiles.join(' | ')
+
+  // Redefine the cacheLife() accepted arguments.
+  return `// Type definitions for Next.js cacheLife configs
+
+declare module 'next/cache' {
+  export { unstable_cache } from 'next/dist/server/web/spec-extension/unstable-cache'
+  export {
+    revalidateTag,
+    revalidatePath,
+  } from 'next/dist/server/web/spec-extension/revalidate'
+  export { unstable_noStore } from 'next/dist/server/web/spec-extension/unstable-no-store'
+
+  import type { CacheLife } from 'next/dist/server/use-cache/cache-life'
+
+  export function unstable_cacheLife(profile: ${profilesEnum} | CacheLife): void
+
+  export { cacheTag as unstable_cacheTag } from 'next/dist/server/use-cache/cache-tag'
+}
+`
+}
+
 const appTypesBasePath = path.join('types', 'app')
 
 export class NextTypesPlugin {
@@ -536,6 +572,7 @@ export class NextTypesPlugin {
   pageExtensions: string[]
   pagesDir: string
   typedRoutes: boolean
+  cacheLifeConfig: undefined | { [profile: string]: CacheLife }
   distDirAbsolutePath: string
 
   constructor(options: Options) {
@@ -547,6 +584,7 @@ export class NextTypesPlugin {
     this.pageExtensions = options.pageExtensions
     this.pagesDir = path.join(this.appDir, '..', 'pages')
     this.typedRoutes = options.typedRoutes
+    this.cacheLifeConfig = options.cacheLifeConfig
     this.distDirAbsolutePath = path.join(this.dir, this.distDir)
     if (this.typedRoutes && !redirectsRewritesTypesProcessed) {
       redirectsRewritesTypesProcessed = true
@@ -780,6 +818,17 @@ export class NextTypesPlugin {
             ) as unknown as webpack.sources.RawSource
           }
 
+          if (this.cacheLifeConfig) {
+            const cacheLifeAssetPath = path.join(
+              assetDirRelative,
+              'types/cache-life.d.ts'
+            )
+
+            assets[cacheLifeAssetPath] = new sources.RawSource(
+              createCustomCacheLifeDefinitions(this.cacheLifeConfig)
+            ) as unknown as webpack.sources.RawSource
+          }
+
           callback()
         }
       )

packages/next/src/export/index.ts

@@ -341,6 +341,7 @@ async function exportAppImpl(
     largePageDataBytes: nextConfig.experimental.largePageDataBytes,
     serverActions: nextConfig.experimental.serverActions,
     serverComponents: enabledDirectories.app,
+    cacheLifeProfiles: nextConfig.experimental.cacheLife,
     nextFontManifest: require(
       join(distDir, 'server', `${NEXT_FONT_MANIFEST}.json`)
     ),

packages/next/src/export/routes/app-route.ts

@@ -40,6 +40,11 @@ export async function exportAppRoute(
   page: string,
   module: AppRouteRouteModule,
   incrementalCache: IncrementalCache | undefined,
+  cacheLifeProfiles:
+    | undefined
+    | {
+        [profile: string]: import('../../server/use-cache/cache-life').CacheLife
+      },
   htmlFilepath: string,
   fileWriter: FileWriter,
   experimental: Required<Pick<ExperimentalConfig, 'after' | 'dynamicIO'>>,
@@ -79,6 +84,7 @@ export async function exportAppRoute(
       waitUntil: afterRunner.context.waitUntil,
       onClose: afterRunner.context.onClose,
       onAfterTaskError: afterRunner.context.onTaskError,
+      cacheLifeProfiles,
       buildId,
     },
   }

packages/next/src/export/worker.ts

@@ -251,6 +251,7 @@ async function exportPageImpl(
         page,
         components.routeModule as AppRouteRouteModule,
         input.renderOpts.incrementalCache,
+        input.renderOpts.cacheLifeProfiles,
         htmlFilepath,
         fileWriter,
         input.renderOpts.experimental,

packages/next/src/server/app-render/types.ts

@@ -147,6 +147,9 @@ export interface RenderOptsPartial {
   nextFontManifest?: DeepReadonly<NextFontManifest>
   isBot?: boolean
   incrementalCache?: import('../lib/incremental-cache').IncrementalCache
+  cacheLifeProfiles?: {
+    [profile: string]: import('../use-cache/cache-life').CacheLife
+  }
   setAppIsrStatus?: (key: string, value: boolean | null) => void
   isRevalidate?: boolean
   nextExport?: boolean

packages/next/src/server/app-render/work-async-storage.external.ts

@@ -6,6 +6,7 @@ import type { FallbackRouteParams } from '../request/fallback-params'
 import type { DeepReadonly } from '../../shared/lib/deep-readonly'
 import type { AppSegmentConfig } from '../../build/segment-config/app/app-segment-config'
 import type { AfterContext } from '../after/after-context'
+import type { CacheLife } from '../use-cache/cache-life'
 
 // Share the instance module in the next-shared layer
 import { workAsyncStorage } from './work-async-storage-instance' with { 'turbopack-transition': 'next-shared' }
@@ -31,6 +32,8 @@ export interface WorkStore {
   readonly fallbackRouteParams: FallbackRouteParams | null
 
   readonly incrementalCache?: IncrementalCache
+  readonly cacheLifeProfiles?: { [profile: string]: CacheLife }
+
   readonly isOnDemandRevalidate?: boolean
   readonly isPrerendering?: boolean
   readonly isRevalidate?: boolean

packages/next/src/server/async-storage/with-work-store.ts

@@ -7,6 +7,7 @@ import type { FetchMetric } from '../base-http'
 import type { RequestLifecycleOpts } from '../base-server'
 import type { FallbackRouteParams } from '../request/fallback-params'
 import type { AppSegmentConfig } from '../../build/segment-config/app/app-segment-config'
+import type { CacheLife } from '../use-cache/cache-life'
 
 import { AfterContext } from '../after/after-context'
 
@@ -26,6 +27,7 @@ export type WorkStoreContext = {
   requestEndedState?: { ended?: boolean }
   isPrefetchRequest?: boolean
   renderOpts: {
+    cacheLifeProfiles?: { [profile: string]: CacheLife }
     incrementalCache?: IncrementalCache
     isOnDemandRevalidate?: boolean
     fetchCache?: AppSegmentConfig['fetchCache']
@@ -108,6 +110,7 @@ export const withWorkStore: WithStore<WorkStore, WorkStoreContext> = <Result>(
       // we fallback to a global incremental cache for edge-runtime locally
       // so that it can access the fs cache without mocks
       renderOpts.incrementalCache || (globalThis as any).__incrementalCache,
+    cacheLifeProfiles: renderOpts.cacheLifeProfiles,
     isRevalidate: renderOpts.isRevalidate,
     isPrerendering: renderOpts.nextExport,
     fetchCache: renderOpts.fetchCache,

packages/next/src/server/base-server.ts

@@ -581,6 +581,7 @@ export default abstract class Server<
       domainLocales: this.nextConfig.i18n?.domains,
       distDir: this.distDir,
       serverComponents: this.enabledDirectories.app,
+      cacheLifeProfiles: this.nextConfig.experimental.cacheLife,
       enableTainting: this.nextConfig.experimental.taint,
       crossOrigin: this.nextConfig.crossOrigin
         ? this.nextConfig.crossOrigin
@@ -2513,6 +2514,7 @@ export default abstract class Server<
               },
               supportsDynamicResponse,
               incrementalCache,
+              cacheLifeProfiles: this.nextConfig.experimental?.cacheLife,
               isRevalidate: isSSG,
               waitUntil: this.getWaitUntil(),
               onClose: res.onClose.bind(res),

packages/next/src/server/config-schema.ts

@@ -270,6 +270,15 @@ export const configSchema: zod.ZodType<NextConfig> = z.lazy(() =>
             static: z.number().optional(),
           })
           .optional(),
+        cacheLife: z
+          .record(
+            z.object({
+              stale: z.number().optional(),
+              revalidate: z.number().optional(),
+              expire: z.number().optional(),
+            })
+          )
+          .optional(),
         clientRouterFilter: z.boolean().optional(),
         clientRouterFilterRedirects: z.boolean().optional(),
         clientRouterFilterAllowedRate: z.number().optional(),

packages/next/src/server/config-shared.ts

@@ -13,6 +13,7 @@ import type { SizeLimit } from '../types'
 import type { ExpireTime } from './lib/revalidate'
 import type { SupportedTestRunners } from '../cli/next-test'
 import type { ExperimentalPPRConfig } from './lib/experimental/ppr'
+import { INFINITE_CACHE } from '../lib/constants'
 
 export type NextConfigComplete = Required<NextConfig> & {
   images: Required<ImageConfigComplete>
@@ -258,6 +259,19 @@ export interface ExperimentalConfig {
     dynamic?: number
     static?: number
   }
+  cacheLife?: {
+    [profile: string]: {
+      // How long the client can cache a value without checking with the server.
+      stale?: number
+      // How frequently you want the cache to refresh on the server.
+      // Stale values may be served while revalidating.
+      revalidate?: number
+      // In the worst case scenario, where you haven't had traffic in a while,
+      // how stale can a value be until you prefer deopting to dynamic.
+      // Must be longer than revalidate.
+      expire?: number
+    }
+  }
   // decimal for percent for possible false positives
   // e.g. 0.01 for 10% potential false matches lower
   // percent increases size of the filter
@@ -1014,6 +1028,13 @@ export const defaultConfig: NextConfig = {
   modularizeImports: undefined,
   outputFileTracingRoot: process.env.NEXT_PRIVATE_OUTPUT_TRACE_ROOT || '',
   experimental: {
+    cacheLife: {
+      default: {
+        stale: undefined, // defaults to staleTimes.static
+        revalidate: 900,
+        expire: INFINITE_CACHE,
+      },
+    },
     multiZoneDraftMode: false,
     appNavFailHandling: Boolean(process.env.NEXT_PRIVATE_FLYING_SHUTTLE),
     flyingShuttle: Boolean(process.env.NEXT_PRIVATE_FLYING_SHUTTLE)

packages/next/src/server/config.ts

@@ -807,6 +807,35 @@ function assignDefaults(
     }
   }
 
+  if (result.experimental?.cacheLife) {
+    const defaultDefault = defaultConfig.experimental?.cacheLife?.['default']
+    if (
+      !defaultDefault ||
+      defaultDefault.revalidate === undefined ||
+      defaultDefault.expire === undefined ||
+      !defaultConfig.experimental?.staleTimes?.static
+    ) {
+      throw new Error('No default cacheLife profile.')
+    }
+    const defaultCacheLifeProfile = result.experimental.cacheLife['default']
+    if (!defaultCacheLifeProfile) {
+      result.experimental.cacheLife['default'] = defaultDefault
+    } else {
+      if (defaultCacheLifeProfile.stale === undefined) {
+        const staticStaleTime = result.experimental.staleTimes?.static
+        defaultCacheLifeProfile.stale =
+          staticStaleTime ?? defaultConfig.experimental?.staleTimes?.static
+      }
+      if (defaultCacheLifeProfile.revalidate === undefined) {
+        defaultCacheLifeProfile.revalidate = defaultDefault.revalidate
+      }
+      if (defaultCacheLifeProfile.expire === undefined) {
+        defaultCacheLifeProfile.expire =
+          result.expireTime ?? defaultDefault.expire
+      }
+    }
+  }
+
   const userProvidedModularizeImports = result.modularizeImports
   // Unfortunately these packages end up re-exporting 10600 modules, for example: https://unpkg.com/browse/@mui/icons-material@5.11.16/esm/index.js.
   // Leveraging modularizeImports tremendously reduces compile times for these.