Propagate expire time to cache-control header and prerender manifest

For the `stale-while-revalidate` value in the `Cache-Control` response
header, Next.js currently uses the configured
[`expireTime`](https://nextjs.org/docs/app/api-reference/config/next-config-js/expireTime),
which defaults to one year.

With the introduction of `"use cache"` and granular [cache
lifetimes](https://nextjs.org/docs/app/api-reference/functions/cacheLife),
users can now set expire times per route — based on the minimum expire
time of all cached functions used by that route.

This PR updates the `stale-while-revalidate` value to reflect the
route's cache lifetime, using the difference between the minimum expire
time and the minimum revalidate time. If no explicit expire time is
defined in cache profiles, the globally configured `expireTime` is used.

Additionally, the collected expire time is added to the prerender
manifest as `initialExpireSeconds`, analogous to
`initialRevalidateSeconds`.

Author: unstubbable

packages/next/errors.json

@@ -644,5 +644,10 @@
   "643": "Invalid \"devIndicator.position\" provided, expected one of %s, received %s",
   "644": "@rspack/core is not available. Please make sure the appropriate Next.js plugin is installed.",
   "645": "@rspack/plugin-react-refresh is not available. Please make sure the appropriate Next.js plugin is installed.",
-  "646": "No span found for compilation"
+  "646": "No span found for compilation",
+  "647": "If providing both the stale and expire options, the expire option must be greater than the stale option. The expire option indicates how many seconds from the start until it can no longer be used.",
+  "648": "If providing both the revalidate and expire options, the expire option must be greater than the revalidate option. The expire option indicates how many seconds from the start until it can no longer be used.",
+  "649": "revalidate must be a number for image-cache",
+  "650": "Pass `Infinity` instead of `false` if you want to cache on the server forever without checking with the origin.",
+  "651": "SSG should not return an image cache value"
 }

packages/next/src/build/index.ts

@@ -3,7 +3,7 @@ import type { PagesManifest } from './webpack/plugins/pages-manifest-plugin'
 import type { ExportPathMap, NextConfigComplete } from '../server/config-shared'
 import type { MiddlewareManifest } from './webpack/plugins/middleware-plugin'
 import type { ActionManifest } from './webpack/plugins/flight-client-entry-plugin'
-import type { Revalidate } from '../server/lib/revalidate'
+import type { CacheControl, Revalidate } from '../server/lib/cache-control'
 
 import '../lib/setup-exception-listeners'
 
@@ -208,7 +208,7 @@ import { turbopackBuild } from './turbopack-build'
 
 type Fallback = null | boolean | string
 
-export interface SsgRoute {
+export interface PrerenderManifestRoute {
   dataRoute: string | null
   experimentalBypassFor?: RouteHas[]
 
@@ -223,10 +223,20 @@ export interface SsgRoute {
   initialStatus?: number
 
   /**
-   * The revalidation configuration for this route.
+   * The revalidate value for this route. This might be inferred from:
+   * - route segment configs
+   * - fetch calls
+   * - unstable_cache
+   * - "use cache"
    */
   initialRevalidateSeconds: Revalidate
 
+  /**
+   * The expire value for this route, which is inferred from the "use cache"
+   * functions that are used by the route, or the expireTime config.
+   */
+  initialExpireSeconds: number | undefined
+
   /**
    * The prefetch data route associated with this page. If not defined, this
    * page does not support prefetching.
@@ -257,7 +267,7 @@ export interface SsgRoute {
   allowHeader: string[]
 }
 
-export interface DynamicSsgRoute {
+export interface DynamicPrerenderManifestRoute {
   dataRoute: string | null
   dataRouteRegex: string | null
   experimentalBypassFor?: RouteHas[]
@@ -327,8 +337,8 @@ const ALLOWED_HEADERS: string[] = [
 
 export type PrerenderManifest = {
   version: 4
-  routes: { [route: string]: SsgRoute }
-  dynamicRoutes: { [route: string]: DynamicSsgRoute }
+  routes: { [route: string]: PrerenderManifestRoute }
+  dynamicRoutes: { [route: string]: DynamicPrerenderManifestRoute }
   notFoundRoutes: string[]
   preview: __ApiPreviewProps
 }
@@ -2135,7 +2145,7 @@ export default async function build(
                   isRoutePPREnabled,
                   isHybridAmp,
                   ssgPageRoutes,
-                  initialRevalidateSeconds: false,
+                  initialCacheControl: undefined,
                   runtime: pageRuntime,
                   pageDuration: undefined,
                   ssgPageDurations: undefined,
@@ -2703,6 +2713,28 @@ export default async function build(
           // If there was no result, there's nothing more to do.
           if (!exportResult) return
 
+          const getCacheControl = (
+            exportPath: string,
+            defaultRevalidate: Revalidate = false
+          ): CacheControl => {
+            const cacheControl =
+              exportResult.byPath.get(exportPath)?.cacheControl
+
+            if (!cacheControl) {
+              return { revalidate: defaultRevalidate }
+            }
+
+            if (
+              cacheControl.revalidate !== false &&
+              cacheControl.revalidate > 0 &&
+              cacheControl.expire === undefined
+            ) {
+              cacheControl.expire = config.expireTime
+            }
+
+            return cacheControl
+          }
+
           if (debugOutput || process.env.NEXT_SSG_FETCH_METRICS === '1') {
             recordFetchMetrics(exportResult)
           }
@@ -2734,7 +2766,7 @@ export default async function build(
 
             let hasRevalidateZero =
               appConfig.revalidate === 0 ||
-              exportResult.byPath.get(page)?.revalidate === 0
+              getCacheControl(page).revalidate === 0
 
             if (hasRevalidateZero && pageInfos.get(page)?.isStatic) {
               // if the page was marked as being static, but it contains dynamic data
@@ -2854,26 +2886,40 @@ export default async function build(
               if (route.pathname === UNDERSCORE_NOT_FOUND_ROUTE) continue
 
               const {
-                revalidate = appConfig.revalidate ?? false,
                 metadata = {},
                 hasEmptyPrelude,
                 hasPostponed,
               } = exportResult.byPath.get(route.pathname) ?? {}
 
+              const cacheControl = getCacheControl(
+                route.pathname,
+                appConfig.revalidate
+              )
+
               pageInfos.set(route.pathname, {
                 ...(pageInfos.get(route.pathname) as PageInfo),
                 hasPostponed,
                 hasEmptyPrelude,
+                // TODO: Enable the following line to show "ISR" status in build
+                // output. Requires different presentation to also work for app
+                // router routes.
+                // See https://vercel.slack.com/archives/C02CDC2ALJH/p1739552318644119?thread_ts=1739550179.439319&cid=C02CDC2ALJH
+                // initialCacheControl: cacheControl,
               })
 
               // update the page (eg /blog/[slug]) to also have the postpone metadata
               pageInfos.set(page, {
                 ...(pageInfos.get(page) as PageInfo),
                 hasPostponed,
                 hasEmptyPrelude,
+                // TODO: Enable the following line to show "ISR" status in build
+                // output. Requires different presentation to also work for app
+                // router routes.
+                // See https://vercel.slack.com/archives/C02CDC2ALJH/p1739552318644119?thread_ts=1739550179.439319&cid=C02CDC2ALJH
+                // initialCacheControl: cacheControl,
               })
 
-              if (revalidate !== 0) {
+              if (cacheControl.revalidate !== 0) {
                 const normalizedRoute = normalizePagePath(route.pathname)
 
                 let dataRoute: string | null
@@ -2906,7 +2952,8 @@ export default async function build(
                     : undefined,
                   experimentalPPR: isRoutePPREnabled,
                   experimentalBypassFor: bypassFor,
-                  initialRevalidateSeconds: revalidate,
+                  initialRevalidateSeconds: cacheControl.revalidate,
+                  initialExpireSeconds: cacheControl.expire,
                   srcRoute: page,
                   dataRoute,
                   prefetchDataRoute,
@@ -2943,8 +2990,11 @@ export default async function build(
               for (const route of dynamicRoutes) {
                 const normalizedRoute = normalizePagePath(route.pathname)
 
-                const { metadata, revalidate } =
-                  exportResult.byPath.get(route.pathname) ?? {}
+                const metadata = exportResult.byPath.get(
+                  route.pathname
+                )?.metadata
+
+                const cacheControl = getCacheControl(route.pathname)
 
                 let dataRoute: string | null = null
                 if (!isAppRouteHandler) {
@@ -2992,7 +3042,7 @@ export default async function build(
                 // found, mark that we should keep the shell forever (`false`).
                 let fallbackRevalidate: Revalidate | undefined =
                   isRoutePPREnabled && fallbackMode === FallbackMode.PRERENDER
-                    ? revalidate ?? false
+                    ? cacheControl.revalidate
                     : undefined
 
                 const fallback: Fallback = fallbackModeToFallbackField(
@@ -3267,10 +3317,11 @@ export default async function build(
                   for (const locale of i18n.locales) {
                     const localePage = `/${locale}${page === '/' ? '' : page}`
 
+                    const cacheControl = getCacheControl(localePage)
+
                     prerenderManifest.routes[localePage] = {
-                      initialRevalidateSeconds:
-                        exportResult.byPath.get(localePage)?.revalidate ??
-                        false,
+                      initialRevalidateSeconds: cacheControl.revalidate,
+                      initialExpireSeconds: cacheControl.expire,
                       experimentalPPR: undefined,
                       renderingMode: undefined,
                       srcRoute: null,
@@ -3284,9 +3335,11 @@ export default async function build(
                     }
                   }
                 } else {
+                  const cacheControl = getCacheControl(page)
+
                   prerenderManifest.routes[page] = {
-                    initialRevalidateSeconds:
-                      exportResult.byPath.get(page)?.revalidate ?? false,
+                    initialRevalidateSeconds: cacheControl.revalidate,
+                    initialExpireSeconds: cacheControl.expire,
                     experimentalPPR: undefined,
                     renderingMode: undefined,
                     srcRoute: null,
@@ -3300,10 +3353,8 @@ export default async function build(
                     allowHeader: ALLOWED_HEADERS,
                   }
                 }
-                // Set Page Revalidation Interval
                 if (pageInfo) {
-                  pageInfo.initialRevalidateSeconds =
-                    exportResult.byPath.get(page)?.revalidate ?? false
+                  pageInfo.initialCacheControl = getCacheControl(page)
                 }
               } else {
                 // For a dynamic SSG page, we did not copy its data exports and only
@@ -3349,15 +3400,11 @@ export default async function build(
                     )
                   }
 
-                  const initialRevalidateSeconds =
-                    exportResult.byPath.get(route.pathname)?.revalidate ?? false
-
-                  if (typeof initialRevalidateSeconds === 'undefined') {
-                    throw new Error("Invariant: page wasn't built")
-                  }
+                  const cacheControl = getCacheControl(route.pathname)
 
                   prerenderManifest.routes[route.pathname] = {
-                    initialRevalidateSeconds,
+                    initialRevalidateSeconds: cacheControl.revalidate,
+                    initialExpireSeconds: cacheControl.expire,
                     experimentalPPR: undefined,
                     renderingMode: undefined,
                     srcRoute: page,
@@ -3371,9 +3418,8 @@ export default async function build(
                     allowHeader: ALLOWED_HEADERS,
                   }
 
-                  // Set route Revalidation Interval
                   if (pageInfo) {
-                    pageInfo.initialRevalidateSeconds = initialRevalidateSeconds
+                    pageInfo.initialCacheControl = cacheControl
                   }
                 }
               }

packages/next/src/build/utils.ts

@@ -81,6 +81,7 @@ import { collectRootParamKeys } from './segment-config/app/collect-root-param-ke
 import { buildAppStaticPaths } from './static-paths/app'
 import { buildPagesStaticPaths } from './static-paths/pages'
 import type { PrerenderedRoute } from './static-paths/types'
+import type { CacheControl } from '../server/lib/cache-control'
 
 export type ROUTER_TYPE = 'pages' | 'app'
 
@@ -346,7 +347,8 @@ export interface PageInfo {
    */
   isRoutePPREnabled: boolean
   ssgPageRoutes: string[] | null
-  initialRevalidateSeconds: number | false
+  // TODO: initialCacheControl should be set per prerendered route.
+  initialCacheControl: CacheControl | undefined
   pageDuration: number | undefined
   ssgPageDurations: number[] | undefined
   runtime: ServerRuntime
@@ -510,12 +512,14 @@ export async function printTreeView(
 
       usedSymbols.add(symbol)
 
-      if (pageInfo?.initialRevalidateSeconds) usedSymbols.add('ISR')
+      // TODO: Rework this to be usable for app router routes.
+      // See https://vercel.slack.com/archives/C02CDC2ALJH/p1739552318644119?thread_ts=1739550179.439319&cid=C02CDC2ALJH
+      if (pageInfo?.initialCacheControl?.revalidate) usedSymbols.add('ISR')
 
       messages.push([
         `${border} ${symbol} ${
-          pageInfo?.initialRevalidateSeconds
-            ? `${item} (ISR: ${pageInfo?.initialRevalidateSeconds} Seconds)`
+          pageInfo?.initialCacheControl
+            ? `${item} (ISR: ${pageInfo?.initialCacheControl.revalidate} Seconds)`
             : item
         }${
           totalDuration > MIN_DURATION

packages/next/src/export/index.ts

@@ -636,8 +636,8 @@ async function exportAppImpl(
     if (options.buildExport) {
       // Update path info by path.
       const info = collector.byPath.get(path) ?? {}
-      if (typeof result.revalidate !== 'undefined') {
-        info.revalidate = result.revalidate
+      if (result.cacheControl) {
+        info.cacheControl = result.cacheControl
       }
       if (typeof result.metadata !== 'undefined') {
         info.metadata = result.metadata

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

@@ -139,7 +139,7 @@ export async function exportAppPage(
     const { metadata } = result
     const {
       flightData,
-      revalidate = false,
+      cacheControl = { revalidate: false },
       postponed,
       fetchTags,
       fetchMetrics,
@@ -151,23 +151,23 @@ export async function exportAppPage(
       throw new Error('Invariant: page postponed without PPR being enabled')
     }
 
-    if (revalidate === 0) {
+    if (cacheControl.revalidate === 0) {
       if (isDynamicError) {
         throw new Error(
           `Page with dynamic = "error" encountered dynamic data method on ${path}.`
         )
       }
       const { staticBailoutInfo = {} } = metadata
 
-      if (revalidate === 0 && debugOutput && staticBailoutInfo?.description) {
+      if (debugOutput && staticBailoutInfo?.description) {
         logDynamicUsageWarning({
           path,
           description: staticBailoutInfo.description,
           stack: staticBailoutInfo.stack,
         })
       }
 
-      return { revalidate: 0, fetchMetrics }
+      return { cacheControl, fetchMetrics }
     }
 
     // If page data isn't available, it means that the page couldn't be rendered
@@ -270,7 +270,7 @@ export async function exportAppPage(
       metadata: hasNextSupport ? meta : undefined,
       hasEmptyPrelude: Boolean(postponed) && html === '',
       hasPostponed: Boolean(postponed),
-      revalidate,
+      cacheControl,
       fetchMetrics,
     }
   } catch (err) {
@@ -298,7 +298,7 @@ export async function exportAppPage(
       })
     }
 
-    return { revalidate: 0, fetchMetrics }
+    return { cacheControl: { revalidate: 0 }, fetchMetrics }
   }
 }