Make cacheLife profiles configurable

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/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

@@ -39,6 +39,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'>>,
@@ -73,6 +78,7 @@ export async function exportAppRoute(
       nextExport: true,
       supportsDynamicResponse: false,
       incrementalCache,
+      cacheLifeProfiles,
       waitUntil: undefined,
       onClose: undefined,
       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

@@ -580,6 +580,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
@@ -2511,6 +2512,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

@@ -258,6 +258,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 +1027,12 @@ export const defaultConfig: NextConfig = {
   modularizeImports: undefined,
   outputFileTracingRoot: process.env.NEXT_PRIVATE_OUTPUT_TRACE_ROOT || '',
   experimental: {
+    cacheLife: {
+      default: {
+        revalidate: 900,
+        expire: Infinity,
+      },
+    },
     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,18 @@ function assignDefaults(
     }
   }
 
+  if (result.experimental?.cacheLife) {
+    const defaultCacheLifeProfile = result.experimental.cacheLife['default']
+    if (!defaultCacheLifeProfile) {
+      throw new Error('No default cacheLife profile.')
+    } else {
+      if (defaultCacheLifeProfile.stale === undefined) {
+        const staticStaleTime = result.experimental.staleTimes?.static
+        defaultCacheLifeProfile.stale = staticStaleTime
+      }
+    }
+  }
+
   const userProvidedModularizeImports = result.modularizeImports
   // Unfortunately these packages end up re-exporting 10600 modules, for example: https://unpkg.com/browse/@mui/[email protected]/esm/index.js.
   // Leveraging modularizeImports tremendously reduces compile times for these.

packages/next/src/server/dev/static-paths-worker.ts

@@ -46,6 +46,7 @@ export async function loadStaticPaths({
   maxMemoryCacheSize,
   requestHeaders,
   cacheHandler,
+  cacheLifeProfiles,
   nextConfigOutput,
   isAppPPRFallbacksEnabled,
   buildId,
@@ -64,6 +65,9 @@ export async function loadStaticPaths({
   maxMemoryCacheSize?: number
   requestHeaders: IncrementalCache['requestHeaders']
   cacheHandler?: string
+  cacheLifeProfiles?: {
+    [profile: string]: import('../../server/use-cache/cache-life').CacheLife
+  }
   nextConfigOutput: 'standalone' | 'export' | undefined
   isAppPPRFallbacksEnabled: boolean | undefined
   buildId: string
@@ -97,6 +101,7 @@ export async function loadStaticPaths({
       distDir,
       requestHeaders,
       cacheHandler,
+      cacheLifeProfiles,
       isrFlushToDisk,
       fetchCacheKeyPrefix,
       maxMemoryCacheSize,

packages/next/src/server/use-cache/cache-life.ts

@@ -1,3 +1,4 @@
+import { workAsyncStorage } from '../app-render/work-async-storage.external'
 import { workUnitAsyncStorage } from '../app-render/work-unit-async-storage.external'
 
 export type CacheLife = {
@@ -15,19 +16,9 @@ export type CacheLife = {
 // Cache-Control: max-age=[stale],s-max-age=[revalidate],stale-while-revalidate=[expire-revalidate],stale-if-error=[expire-revalidate]
 // Except that stale-while-revalidate/stale-if-error only applies to shared caches - not private caches.
 
-const cacheLifeProfileMap: Map<string, CacheLife> = new Map()
-
 // The default revalidates relatively frequently but doesn't expire to ensure it's always
 // able to serve fast results but by default doesn't hang.
 
-export const defaultCacheLife = {
-  stale: Number(process.env.__NEXT_CLIENT_ROUTER_STATIC_STALETIME),
-  revalidate: 15 * 60, // Note: This is a new take on the defaults.
-  expire: Infinity,
-}
-
-cacheLifeProfileMap.set('default', defaultCacheLife)
-
 type CacheLifeProfiles = 'default' // TODO: Generate from the config
 
 function validateCacheLife(profile: CacheLife) {
@@ -99,9 +90,22 @@ export function cacheLife(profile: CacheLifeProfiles | CacheLife): void {
   }
 
   if (typeof profile === 'string') {
-    const configuredProfile = cacheLifeProfileMap.get(profile)
+    const workStore = workAsyncStorage.getStore()
+    if (!workStore) {
+      throw new Error(
+        'cacheLife() can only be called during App Router rendering at the moment.'
+      )
+    }
+    if (!workStore.cacheLifeProfiles) {
+      throw new Error(
+        'cacheLifeProfiles should always be provided. This is a bug in Next.js.'
+      )
+    }
+
+    // TODO: This should be globally available and not require an AsyncLocalStorage.
+    const configuredProfile = workStore.cacheLifeProfiles[profile]
     if (configuredProfile === undefined) {
-      if (cacheLifeProfileMap.has(profile.trim())) {
+      if (workStore.cacheLifeProfiles[profile.trim()]) {
         throw new Error(
           `Unknown cacheLife profile "${profile}" is not configured in next.config.js\n` +
             `Did you mean "${profile.trim()}" without the spaces?`

packages/next/src/server/use-cache/use-cache-wrapper.ts

@@ -29,7 +29,6 @@ import {
   getClientReferenceManifestSingleton,
   getServerModuleMap,
 } from '../app-render/encryption-utils'
-import { defaultCacheLife } from './cache-life'
 import type { CacheScopeStore } from '../async-storage/cache-scope.external'
 
 const isEdgeRuntime = process.env.NEXT_RUNTIME === 'edge'
@@ -172,6 +171,22 @@ function generateCacheEntryWithCacheContext(
   encodedArguments: FormData | string,
   fn: any
 ) {
+  if (!workStore.cacheLifeProfiles) {
+    throw new Error(
+      'cacheLifeProfiles should always be provided. This is a bug in Next.js.'
+    )
+  }
+  const defaultCacheLife = workStore.cacheLifeProfiles['default']
+  if (
+    !defaultCacheLife ||
+    defaultCacheLife.revalidate === undefined ||
+    defaultCacheLife.expire === undefined ||
+    defaultCacheLife.stale === undefined
+  ) {
+    throw new Error(
+      'A default cacheLife profile must always be provided. This is a bug in Next.js.'
+    )
+  }
   // Initialize the Store for this Cache entry.
   const cacheStore: UseCacheStore = {
     type: 'cache',

packages/next/src/server/web/adapter.ts

@@ -255,6 +255,8 @@ export async function adapter(
                 page: '/', // Fake Work
                 fallbackRouteParams: null,
                 renderOpts: {
+                  cacheLifeProfiles:
+                    params.request.nextConfig?.experimental?.cacheLife,
                   experimental: {
                     after: isAfterEnabled,
                     isRoutePPREnabled: false,

packages/next/src/server/web/types.ts

@@ -15,7 +15,7 @@ export interface RequestData {
     basePath?: string
     i18n?: I18NConfig | null
     trailingSlash?: boolean
-    experimental?: Pick<ExperimentalConfig, 'after'>
+    experimental?: Pick<ExperimentalConfig, 'after' | 'cacheLife'>
   }
   page?: {
     name?: string