Rename swrDelta config to expireTime (#71159)

As discussed this updates the `swrDelta` config to `expireTime` as it's
more clear what the config is doing since it's how long the cache is
allowed to be kept before it's fully expired.

docs/02-app/02-api-reference/05-next-config-js/swrDelta.mdx

@@ -1,18 +1,18 @@
 ---
-title: swrDelta
+title: expireTime
 description: Set a custom stale-while-revalidate period for ISR enabled pages.
 ---
 
 {/* The content of this doc is shared between the app and pages router. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
 
 You can specify a custom stale-while-revalidate period for CDNs to consume in the `Cache-Control` header for ISR enabled pages.
 
-Open `next.config.js` and add the `swrDelta` config:
+Open `next.config.js` and add the `expireTime` config:
 
 ```js filename="next.config.js"
 module.exports = {
   // one year in seconds
-  swrDelta: 31536000,
+  expireTime: 31536000,
 }
 ```
 

packages/next/src/export/index.ts

@@ -354,7 +354,7 @@ async function exportAppImpl(
     deploymentId: nextConfig.deploymentId,
     experimental: {
       clientTraceMetadata: nextConfig.experimental.clientTraceMetadata,
-      swrDelta: nextConfig.swrDelta,
+      expireTime: nextConfig.expireTime,
       after: nextConfig.experimental.after ?? false,
       dynamicIO: nextConfig.experimental.dynamicIO ?? false,
     },

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

@@ -5,7 +5,7 @@ import type { ClientReferenceManifest } from '../../build/webpack/plugins/flight
 import type { NextFontManifest } from '../../build/webpack/plugins/next-font-manifest-plugin'
 import type { ParsedUrlQuery } from 'querystring'
 import type { AppPageModule } from '../route-modules/app-page/module'
-import type { SwrDelta } from '../lib/revalidate'
+import type { ExpireTime } from '../lib/revalidate'
 import type { LoadingModuleData } from '../../shared/lib/app-router-context.shared-runtime'
 import type { DeepReadonly } from '../../shared/lib/deep-readonly'
 import type { __ApiPreviewProps } from '../api-utils'
@@ -174,7 +174,7 @@ export interface RenderOptsPartial {
      * prerendering.
      */
     isRoutePPREnabled?: boolean
-    swrDelta: SwrDelta | undefined
+    expireTime: ExpireTime | undefined
     clientTraceMetadata: string[] | undefined
     after: boolean
     dynamicIO: boolean

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

@@ -76,7 +76,7 @@ import { setConfig } from '../shared/lib/runtime-config.external'
 import {
   formatRevalidate,
   type Revalidate,
-  type SwrDelta,
+  type ExpireTime,
 } from './lib/revalidate'
 import { execOnce } from '../shared/lib/utils'
 import { isBlockedPage } from './utils'
@@ -399,7 +399,7 @@ export default abstract class Server<
       generateEtags: boolean
       poweredByHeader: boolean
       revalidate?: Revalidate
-      swrDelta?: SwrDelta
+      expireTime?: ExpireTime
     }
   ): Promise<void>
 
@@ -598,7 +598,7 @@ export default abstract class Server<
       // @ts-expect-error internal field not publicly exposed
       isExperimentalCompile: this.nextConfig.experimental.isExperimentalCompile,
       experimental: {
-        swrDelta: this.nextConfig.swrDelta,
+        expireTime: this.nextConfig.expireTime,
         clientTraceMetadata: this.nextConfig.experimental.clientTraceMetadata,
         after: this.nextConfig.experimental.after ?? false,
         dynamicIO: this.nextConfig.experimental.dynamicIO ?? false,
@@ -1735,7 +1735,7 @@ export default abstract class Server<
         generateEtags,
         poweredByHeader,
         revalidate,
-        swrDelta: this.nextConfig.swrDelta,
+        expireTime: this.nextConfig.expireTime,
       })
       res.statusCode = originalStatus
     }
@@ -3341,7 +3341,7 @@ export default abstract class Server<
           'Cache-Control',
           formatRevalidate({
             revalidate: cacheEntry.revalidate,
-            swrDelta: this.nextConfig.swrDelta,
+            expireTime: this.nextConfig.expireTime,
           })
         )
       }
@@ -3364,7 +3364,7 @@ export default abstract class Server<
           'Cache-Control',
           formatRevalidate({
             revalidate: cacheEntry.revalidate,
-            swrDelta: this.nextConfig.swrDelta,
+            expireTime: this.nextConfig.expireTime,
           })
         )
       }

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

@@ -627,7 +627,7 @@ export const configSchema: zod.ZodType<NextConfig> = z.lazy(() =>
     skipMiddlewareUrlNormalize: z.boolean().optional(),
     skipTrailingSlashRedirect: z.boolean().optional(),
     staticPageGenerationTimeout: z.number().optional(),
-    swrDelta: z.number().optional(),
+    expireTime: z.number().optional(),
     target: z.string().optional(),
     trailingSlash: z.boolean().optional(),
     transpilePackages: z.array(z.string()).optional(),

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

@@ -10,7 +10,7 @@ import type { SubresourceIntegrityAlgorithm } from '../build/webpack/plugins/sub
 import type { WEB_VITALS } from '../shared/lib/utils'
 import type { NextParsedUrlQuery } from './request-meta'
 import type { SizeLimit } from '../types'
-import type { SwrDelta } from './lib/revalidate'
+import type { ExpireTime } from './lib/revalidate'
 import type { SupportedTestRunners } from '../cli/next-test'
 import type { ExperimentalPPRConfig } from './lib/experimental/ppr'
 
@@ -268,9 +268,9 @@ export interface ExperimentalConfig {
   fetchCacheKeyPrefix?: string
   optimisticClientCache?: boolean
   /**
-   * @deprecated use config.swrDelta instead
+   * @deprecated use config.expireTime instead
    */
-  swrDelta?: SwrDelta
+  expireTime?: ExpireTime
   middlewarePrefetch?: 'strict' | 'flexible'
   manualClientBasePath?: boolean
   /**
@@ -915,7 +915,7 @@ export interface NextConfig extends Record<string, any> {
   /**
    * period (in seconds) where the server allow to serve stale cache
    */
-  swrDelta?: SwrDelta
+  expireTime?: ExpireTime
 
   /**
    * Enable experimental features. Note that all experimental features are subject to breaking changes in the future.
@@ -1008,7 +1008,7 @@ export const defaultConfig: NextConfig = {
     keepAlive: true,
   },
   logging: {},
-  swrDelta: process.env.__NEXT_TEST_MODE ? undefined : 31536000,
+  expireTime: process.env.__NEXT_TEST_MODE ? undefined : 31536000,
   staticPageGenerationTimeout: 60,
   output: !!process.env.NEXT_PRIVATE_STANDALONE ? 'standalone' : undefined,
   modularizeImports: undefined,

packages/next/src/server/config.ts

@@ -503,7 +503,7 @@ function assignDefaults(
   warnOptionHasBeenMovedOutOfExperimental(
     result,
     'swrDelta',
-    'swrDelta',
+    'expireTime',
     configFileName,
     silent
   )

packages/next/src/server/lib/revalidate.ts

@@ -8,18 +8,21 @@ import { CACHE_ONE_YEAR } from '../../lib/constants'
  * value for this option.
  */
 export type Revalidate = number | false
-export type SwrDelta = number
+export type ExpireTime = number
 
 export function formatRevalidate({
   revalidate,
-  swrDelta,
+  expireTime,
 }: {
   revalidate: Revalidate
-  swrDelta?: SwrDelta
+  expireTime?: ExpireTime
 }): string {
-  const swrHeader = swrDelta
-    ? `stale-while-revalidate=${swrDelta}`
-    : 'stale-while-revalidate'
+  const swrHeader =
+    typeof revalidate === 'number' && expireTime !== undefined
+      ? revalidate >= expireTime
+        ? ''
+        : `stale-while-revalidate=${expireTime - revalidate}`
+      : 'stale-while-revalidate'
 
   if (revalidate === 0) {
     return 'private, no-cache, no-store, max-age=0, must-revalidate'

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

@@ -22,7 +22,7 @@ import type { PagesAPIRouteModule } from './route-modules/pages-api/module'
 import type { UrlWithParsedQuery } from 'url'
 import type { ParsedUrlQuery } from 'querystring'
 import type { ParsedUrl } from '../shared/lib/router/utils/parse-url'
-import type { Revalidate, SwrDelta } from './lib/revalidate'
+import type { Revalidate, ExpireTime } from './lib/revalidate'
 
 import fs from 'fs'
 import { join, resolve } from 'path'
@@ -465,7 +465,7 @@ export default class NextNodeServer extends BaseServer<
       generateEtags: boolean
       poweredByHeader: boolean
       revalidate: Revalidate | undefined
-      swrDelta: SwrDelta | undefined
+      expireTime: ExpireTime | undefined
     }
   ): Promise<void> {
     return sendRenderResult({
@@ -476,7 +476,7 @@ export default class NextNodeServer extends BaseServer<
       generateEtags: options.generateEtags,
       poweredByHeader: options.poweredByHeader,
       revalidate: options.revalidate,
-      swrDelta: options.swrDelta,
+      expireTime: options.expireTime,
     })
   }
 

packages/next/src/server/render.tsx

@@ -36,7 +36,7 @@ import type { NextFontManifest } from '../build/webpack/plugins/next-font-manife
 import type { PagesModule } from './route-modules/pages/module'
 import type { ComponentsEnhancer } from '../shared/lib/utils'
 import type { NextParsedUrlQuery } from './request-meta'
-import type { Revalidate, SwrDelta } from './lib/revalidate'
+import type { Revalidate, ExpireTime } from './lib/revalidate'
 import type { COMPILER_NAMES } from '../shared/lib/constants'
 
 import React, { type JSX } from 'react'
@@ -284,7 +284,7 @@ export type RenderOptsPartial = {
   isServerAction?: boolean
   isExperimentalCompile?: boolean
   isPrefetch?: boolean
-  swrDelta?: SwrDelta
+  expireTime?: ExpireTime
   experimental: {
     clientTraceMetadata?: string[]
   }
@@ -456,7 +456,7 @@ export async function renderToHTMLImpl(
     images,
     runtime: globalRuntime,
     isExperimentalCompile,
-    swrDelta,
+    expireTime,
   } = renderOpts
   const { App } = extra
 
@@ -517,7 +517,7 @@ export async function renderToHTMLImpl(
       'Cache-Control',
       formatRevalidate({
         revalidate: false,
-        swrDelta,
+        expireTime,
       })
     )
     isAutoExport = false

packages/next/src/server/send-payload.ts

@@ -1,6 +1,6 @@
 import type { IncomingMessage, ServerResponse } from 'http'
 import type RenderResult from './render-result'
-import type { Revalidate, SwrDelta } from './lib/revalidate'
+import type { Revalidate, ExpireTime } from './lib/revalidate'
 
 import { isResSent } from '../shared/lib/utils'
 import { generateETag } from './lib/etag'
@@ -40,7 +40,7 @@ export async function sendRenderResult({
   generateEtags,
   poweredByHeader,
   revalidate,
-  swrDelta,
+  expireTime,
 }: {
   req: IncomingMessage
   res: ServerResponse
@@ -49,7 +49,7 @@ export async function sendRenderResult({
   generateEtags: boolean
   poweredByHeader: boolean
   revalidate: Revalidate | undefined
-  swrDelta: SwrDelta | undefined
+  expireTime: ExpireTime | undefined
 }): Promise<void> {
   if (isResSent(res)) {
     return
@@ -66,7 +66,7 @@ export async function sendRenderResult({
       'Cache-Control',
       formatRevalidate({
         revalidate,
-        swrDelta,
+        expireTime,
       })
     )
   }

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

@@ -10,7 +10,7 @@ import type {
   Options,
   RouteHandler,
 } from './base-server'
-import type { Revalidate, SwrDelta } from './lib/revalidate'
+import type { Revalidate, ExpireTime } from './lib/revalidate'
 
 import { byteLength } from './api-utils/web'
 import BaseServer, { NoFallbackError } from './base-server'
@@ -268,7 +268,7 @@ export default class NextWebServer extends BaseServer<
       generateEtags: boolean
       poweredByHeader: boolean
       revalidate: Revalidate | undefined
-      swrDelta: SwrDelta | undefined
+      expireTime: ExpireTime | undefined
     }
   ): Promise<void> {
     res.setHeader('X-Edge-Runtime', '1')