Stabilize swrDelta config (#66108)

Alternative to https://github.com/vercel/next.js/pull/65867 this
stabilizes our `swrDelta` config that allows customizing the
`stale-while-revalidate` period that is included in the `Cache-Control`
header for ISR enabled routes.

This is not a breaking change itself as no default value is provided as
is the case already.

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

@@ -0,0 +1,19 @@
+---
+title: swrDelta
+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:
+
+```js filename="next.config.js"
+module.exports = {
+  // one year in seconds
+  swrDelta: 31536000,
+}
+```
+
+Now instead of an empty `stale-while-revalidate` period being provided in the `Cache-Control` header, the custom period will be included.

packages/next/src/export/index.ts

@@ -421,7 +421,7 @@ export async function exportAppImpl(
     experimental: {
       isAppPPREnabled: checkIsAppPPREnabled(nextConfig.experimental.ppr),
       clientTraceMetadata: nextConfig.experimental.clientTraceMetadata,
-      swrDelta: nextConfig.experimental.swrDelta,
+      swrDelta: nextConfig.swrDelta,
       after: nextConfig.experimental.after ?? false,
     },
   }

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

@@ -569,7 +569,7 @@ export default abstract class Server<
       isExperimentalCompile: this.nextConfig.experimental.isExperimentalCompile,
       experimental: {
         isAppPPREnabled,
-        swrDelta: this.nextConfig.experimental.swrDelta,
+        swrDelta: this.nextConfig.swrDelta,
         clientTraceMetadata: this.nextConfig.experimental.clientTraceMetadata,
         after: this.nextConfig.experimental.after ?? false,
       },
@@ -1628,7 +1628,7 @@ export default abstract class Server<
         generateEtags,
         poweredByHeader,
         revalidate,
-        swrDelta: this.nextConfig.experimental.swrDelta,
+        swrDelta: this.nextConfig.swrDelta,
       })
       res.statusCode = originalStatus
     }
@@ -2913,7 +2913,7 @@ export default abstract class Server<
           'Cache-Control',
           formatRevalidate({
             revalidate: cacheEntry.revalidate,
-            swrDelta: this.nextConfig.experimental.swrDelta,
+            swrDelta: this.nextConfig.swrDelta,
           })
         )
       }
@@ -2935,7 +2935,7 @@ export default abstract class Server<
           'Cache-Control',
           formatRevalidate({
             revalidate: cacheEntry.revalidate,
-            swrDelta: this.nextConfig.experimental.swrDelta,
+            swrDelta: this.nextConfig.swrDelta,
           })
         )
       }

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

@@ -290,7 +290,6 @@ export const configSchema: zod.ZodType<NextConfig> = z.lazy(() =>
         externalMiddlewareRewritesResolve: z.boolean().optional(),
         fallbackNodePolyfills: z.literal(false).optional(),
         fetchCacheKeyPrefix: z.string().optional(),
-        swrDelta: z.number().optional(),
         flyingShuttle: z.boolean().optional(),
         forceSwcTransforms: z.boolean().optional(),
         fullySpecified: z.boolean().optional(),
@@ -589,6 +588,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(),
     target: z.string().optional(),
     trailingSlash: z.boolean().optional(),
     transpilePackages: z.array(z.string()).optional(),

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

@@ -225,7 +225,7 @@ export interface ExperimentalConfig {
   fetchCacheKeyPrefix?: string
   optimisticClientCache?: boolean
   /**
-   * period (in seconds) where the server allow to serve stale cache
+   * @deprecated use config.swrDelta instead
    */
   swrDelta?: SwrDelta
   middlewarePrefetch?: 'strict' | 'flexible'
@@ -839,6 +839,11 @@ export interface NextConfig extends Record<string, any> {
     }
   }
 
+  /**
+   * period (in seconds) where the server allow to serve stale cache
+   */
+  swrDelta?: SwrDelta
+
   /**
    * Enable experimental features. Note that all experimental features are subject to breaking changes in the future.
    */
@@ -906,6 +911,7 @@ export const defaultConfig: NextConfig = {
   httpAgentOptions: {
     keepAlive: true,
   },
+  swrDelta: undefined,
   staticPageGenerationTimeout: 60,
   output: !!process.env.NEXT_PRIVATE_STANDALONE ? 'standalone' : undefined,
   modularizeImports: undefined,
@@ -923,7 +929,6 @@ export const defaultConfig: NextConfig = {
     fetchCacheKeyPrefix: '',
     middlewarePrefetch: 'flexible',
     optimisticClientCache: true,
-    swrDelta: undefined,
     manualClientBasePath: false,
     cpus: Math.max(
       1,

packages/next/src/server/config.ts

@@ -503,6 +503,13 @@ function assignDefaults(
     configFileName,
     silent
   )
+  warnOptionHasBeenMovedOutOfExperimental(
+    result,
+    'swrDelta',
+    'swrDelta',
+    configFileName,
+    silent
+  )
 
   if ((result.experimental as any).outputStandalone) {
     if (!silent) {