[cache components] move experimental.cacheHandlers out of experimental

ztanner · ztanner · commit 44851a7c6a86 · 2025-10-20T22:14:12.000-07:00
diff --git a/crates/next-custom-transforms/src/transforms/server_actions.rs b/crates/next-custom-transforms/src/transforms/server_actions.rs
@@ -3191,7 +3191,7 @@ fn emit_error(error_kind: ServerActionsErrorKind) {
             span,
             formatdoc! {
                 r#"
-                    Unknown cache kind "{cache_kind}". Please configure a cache handler for this kind in the `experimental.cacheHandlers` object in your Next.js config.
+                    Unknown cache kind "{cache_kind}". Please configure a cache handler for this kind in the `cacheHandlers` object in your Next.js config.
                 "#
             },
         ),
diff --git a/crates/next-custom-transforms/tests/errors/server-actions/server-graph/16/output.stderr b/crates/next-custom-transforms/tests/errors/server-actions/server-graph/16/output.stderr
@@ -1,4 +1,4 @@
-  x Unknown cache kind "x". Please configure a cache handler for this kind in the `experimental.cacheHandlers` object in your Next.js config.
+  x Unknown cache kind "x". Please configure a cache handler for this kind in the `cacheHandlers` object in your Next.js config.
   | 
    ,-[input.js:1:1]
  1 | 'use cache: x'
diff --git a/crates/next-custom-transforms/tests/errors/server-actions/server-graph/17/output.stderr b/crates/next-custom-transforms/tests/errors/server-actions/server-graph/17/output.stderr
@@ -1,4 +1,4 @@
-  x Unknown cache kind "x". Please configure a cache handler for this kind in the `experimental.cacheHandlers` object in your Next.js config.
+  x Unknown cache kind "x". Please configure a cache handler for this kind in the `cacheHandlers` object in your Next.js config.
   | 
    ,-[input.js:2:1]
  1 | export async function foo() {
diff --git a/packages/next/errors.json b/packages/next/errors.json
@@ -898,5 +898,6 @@
   "897": "Expected HTML document to start with doctype prefix",
   "898": "When using Cache Components, all `generateStaticParams` functions must return at least one result. This is to ensure that we can perform build-time validation that there is no other dynamic accesses that would cause a runtime error.\n\nLearn more: https://nextjs.org/docs/messages/empty-generate-static-params",
   "899": "Both \"%s\" and \"%s\" files are detected. Please use \"%s\" instead. Learn more: https://nextjs.org/docs/messages/middleware-to-proxy",
-  "900": "Both %s file \"./%s\" and %s file \"./%s\" are detected. Please use \"./%s\" only. Learn more: https://nextjs.org/docs/messages/middleware-to-proxy"
+  "900": "Both %s file \"./%s\" and %s file \"./%s\" are detected. Please use \"./%s\" only. Learn more: https://nextjs.org/docs/messages/middleware-to-proxy",
+  "901": "Invalid \"cacheHandlers\" provided, expected an object e.g. { default: '/my-handler.js' }, received %s"
 }
diff --git a/packages/next/src/build/collect-build-traces.ts b/packages/next/src/build/collect-build-traces.ts
@@ -124,8 +124,7 @@ export async function collectBuildTraces({
         })
       )
 
-      const { cacheHandler } = config
-      const { cacheHandlers } = config.experimental
+      const { cacheHandler, cacheHandlers } = config
 
       // ensure we trace any dependencies needed for custom
       // incremental cache handler
diff --git a/packages/next/src/build/entries.ts b/packages/next/src/build/entries.ts
@@ -616,9 +616,7 @@ export function getEdgeServerEntry(opts: {
       middlewareConfig: Buffer.from(
         JSON.stringify(opts.middlewareConfig || {})
       ).toString('base64'),
-      cacheHandlers: JSON.stringify(
-        opts.config.experimental.cacheHandlers || {}
-      ),
+      cacheHandlers: JSON.stringify(opts.config.cacheHandlers || {}),
     }
 
     return {
@@ -685,7 +683,7 @@ export function getEdgeServerEntry(opts: {
       JSON.stringify(opts.middlewareConfig || {})
     ).toString('base64'),
     serverActions: opts.config.experimental.serverActions,
-    cacheHandlers: JSON.stringify(opts.config.experimental.cacheHandlers || {}),
+    cacheHandlers: JSON.stringify(opts.config.cacheHandlers || {}),
   }
 
   return {
diff --git a/packages/next/src/build/index.ts b/packages/next/src/build/index.ts
@@ -2223,7 +2223,7 @@ export default async function build(
                             cacheComponents: isAppCacheComponentsEnabled,
                             authInterrupts: isAuthInterruptsEnabled,
                             cacheHandler: config.cacheHandler,
-                            cacheHandlers: config.experimental.cacheHandlers,
+                            cacheHandlers: config.cacheHandlers,
                             isrFlushToDisk: ciEnvironment.hasNextSupport
                               ? false
                               : config.experimental.isrFlushToDisk,
@@ -2518,7 +2518,7 @@ export default async function build(
           const normalizedCacheHandlers: Record<string, string> = {}
 
           for (const [key, value] of Object.entries(
-            config.experimental.cacheHandlers || {}
+            config.cacheHandlers || {}
           )) {
             if (key && value) {
               normalizedCacheHandlers[key] = path.relative(distDir, value)
@@ -2538,9 +2538,9 @@ export default async function build(
               cacheHandler: cacheHandler
                 ? path.relative(distDir, cacheHandler)
                 : config.cacheHandler,
+              cacheHandlers: normalizedCacheHandlers,
               experimental: {
                 ...config.experimental,
-                cacheHandlers: normalizedCacheHandlers,
                 trustHostHeader: ciEnvironment.hasNextSupport,
                 isExperimentalCompile: isCompileMode,
               },
diff --git a/packages/next/src/build/static-paths/app.ts b/packages/next/src/build/static-paths/app.ts
@@ -747,7 +747,7 @@ export async function buildAppStaticPaths({
   isrFlushToDisk?: boolean
   fetchCacheKeyPrefix?: string
   cacheHandler?: string
-  cacheHandlers?: NextConfigComplete['experimental']['cacheHandlers']
+  cacheHandlers?: NextConfigComplete['cacheHandlers']
   cacheLifeProfiles?: {
     [profile: string]: import('../../server/use-cache/cache-life').CacheLife
   }
diff --git a/packages/next/src/build/swc/index.ts b/packages/next/src/build/swc/index.ts
@@ -859,26 +859,20 @@ function bindingToApi(
           ? path.relative(projectPath, nextConfigSerializable.cacheHandler)
           : nextConfigSerializable.cacheHandler)
     }
-    if (nextConfigSerializable.experimental?.cacheHandlers) {
-      nextConfigSerializable.experimental = {
-        ...nextConfigSerializable.experimental,
-        cacheHandlers: Object.fromEntries(
-          Object.entries(
-            nextConfigSerializable.experimental.cacheHandlers as Record<
-              string,
-              string
-            >
-          )
-            .filter(([_, value]) => value != null)
-            .map(([key, value]) => [
-              key,
-              './' +
-                (path.isAbsolute(value)
-                  ? path.relative(projectPath, value)
-                  : value),
-            ])
-        ),
-      }
+    if (nextConfigSerializable.cacheHandlers) {
+      nextConfigSerializable.cacheHandlers = Object.fromEntries(
+        Object.entries(
+          nextConfigSerializable.cacheHandlers as Record<string, string>
+        )
+          .filter(([_, value]) => value != null)
+          .map(([key, value]) => [
+            key,
+            './' +
+              (path.isAbsolute(value)
+                ? path.relative(projectPath, value)
+                : value),
+          ])
+      )
     }
 
     if (nextConfigSerializable.turbopack != null) {
diff --git a/packages/next/src/build/swc/options.ts b/packages/next/src/build/swc/options.ts
@@ -92,7 +92,7 @@ function getBaseSWCOptions({
   serverReferenceHashSalt: string
   bundleLayer?: WebpackLayerName
   isCacheComponents?: boolean
-  cacheHandlers?: ExperimentalConfig['cacheHandlers']
+  cacheHandlers?: NextConfig['cacheHandlers']
   useCacheEnabled?: boolean
   trackDynamicImports?: boolean
 }) {
@@ -412,7 +412,7 @@ export function getLoaderSWCOptions({
   serverComponents?: boolean
   serverReferenceHashSalt: string
   bundleLayer?: WebpackLayerName
-  cacheHandlers: ExperimentalConfig['cacheHandlers']
+  cacheHandlers: NextConfig['cacheHandlers']
   useCacheEnabled?: boolean
   trackDynamicImports?: boolean
 }) {
diff --git a/packages/next/src/build/webpack/loaders/next-swc-loader.ts b/packages/next/src/build/webpack/loaders/next-swc-loader.ts
@@ -164,7 +164,7 @@ async function loaderTransform(
     serverReferenceHashSalt,
     bundleLayer,
     esm,
-    cacheHandlers: nextConfig.experimental?.cacheHandlers,
+    cacheHandlers: nextConfig.cacheHandlers,
     useCacheEnabled: nextConfig.experimental?.useCache,
     trackDynamicImports,
   })
diff --git a/packages/next/src/export/worker.ts b/packages/next/src/export/worker.ts
@@ -360,7 +360,7 @@ export async function exportPages(
     // skip writing to disk in minimal mode for now, pending some
     // changes to better support it
     flushToDisk: !hasNextSupport,
-    cacheHandlers: nextConfig.experimental.cacheHandlers,
+    cacheHandlers: nextConfig.cacheHandlers,
   })
 
   renderOpts.incrementalCache = incrementalCache
diff --git a/packages/next/src/server/config-schema.ts b/packages/next/src/server/config-schema.ts
@@ -356,6 +356,7 @@ export const configSchema: zod.ZodType<NextConfig> = z.lazy(() =>
     bundlePagesRouterDependencies: z.boolean().optional(),
     cacheComponents: z.boolean().optional(),
     cacheHandler: z.string().min(1).optional(),
+    cacheHandlers: z.record(z.string(), z.string().optional()).optional(),
     cacheLife: z
       .record(
         z.object({
diff --git a/packages/next/src/server/config-shared.ts b/packages/next/src/server/config-shared.ts
@@ -272,12 +272,8 @@ export interface LoggingConfig {
 export interface ExperimentalConfig {
   adapterPath?: string
   useSkewCookie?: boolean
-  cacheHandlers?: {
-    default?: string
-    remote?: string
-    static?: string
-    [handlerName: string]: string | undefined
-  }
+  /** @deprecated use top-level `cacheHandlers` instead */
+  cacheHandlers?: NextConfig['cacheHandlers']
   multiZoneDraftMode?: boolean
   appNavFailHandling?: boolean
   prerenderEarlyExit?: boolean
@@ -308,19 +304,7 @@ export interface ExperimentalConfig {
   /**
    * @deprecated use top-level `cacheLife` instead
    */
-  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
-    }
-  }
+  cacheLife?: NextConfig['cacheLife']
   // decimal for percent for possible false positives
   // e.g. 0.01 for 10% potential false matches lower
   // percent increases size of the filter
@@ -1017,6 +1001,13 @@ export interface NextConfig {
    */
   cacheHandler?: string | undefined
 
+  cacheHandlers?: {
+    default?: string
+    remote?: string
+    static?: string
+    [handlerName: string]: string | undefined
+  }
+
   /**
    * Configure the in-memory cache size in bytes. Defaults to 50 MB.
    * If `cacheMaxMemorySize: 0`, this disables in-memory caching entirely.
@@ -1452,14 +1443,14 @@ export const defaultConfig = Object.freeze({
       expire: 60 * 60 * 24 * 365, // 1 year
     },
   },
+  cacheHandlers: {
+    default: process.env.NEXT_DEFAULT_CACHE_HANDLER_PATH,
+    remote: process.env.NEXT_REMOTE_CACHE_HANDLER_PATH,
+    static: process.env.NEXT_STATIC_CACHE_HANDLER_PATH,
+  },
   experimental: {
     adapterPath: process.env.NEXT_ADAPTER_PATH || undefined,
     useSkewCookie: false,
-    cacheHandlers: {
-      default: process.env.NEXT_DEFAULT_CACHE_HANDLER_PATH,
-      remote: process.env.NEXT_REMOTE_CACHE_HANDLER_PATH,
-      static: process.env.NEXT_STATIC_CACHE_HANDLER_PATH,
-    },
     cssChunking: true,
     multiZoneDraftMode: false,
     appNavFailHandling: false,
diff --git a/packages/next/src/server/config.ts b/packages/next/src/server/config.ts
@@ -744,6 +744,13 @@ function assignDefaultsAndValidate(
     configFileName,
     silent
   )
+  warnOptionHasBeenMovedOutOfExperimental(
+    result,
+    'cacheHandlers',
+    'cacheHandlers',
+    configFileName,
+    silent
+  )
 
   if ((result.experimental as any).outputStandalone) {
     if (!silent) {
@@ -1149,13 +1156,13 @@ function assignDefaultsAndValidate(
   if (result.experimental?.cacheHandlers) {
     const allowedHandlerNameRegex = /[a-z-]/
 
-    if (typeof result.experimental.cacheHandlers !== 'object') {
+    if (typeof result.cacheHandlers !== 'object') {
       throw new Error(
-        `Invalid "experimental.cacheHandlers" provided, expected an object e.g. { default: '/my-handler.js' }, received ${JSON.stringify(result.experimental.cacheHandlers)}`
+        `Invalid "cacheHandlers" provided, expected an object e.g. { default: '/my-handler.js' }, received ${JSON.stringify(result.cacheHandlers)}`
       )
     }
 
-    const handlerKeys = Object.keys(result.experimental.cacheHandlers)
+    const handlerKeys = Object.keys(result.cacheHandlers)
     const invalidHandlerItems: Array<{ key: string; reason: string }> = []
 
     for (const key of handlerKeys) {
@@ -1172,7 +1179,7 @@ function assignDefaultsAndValidate(
         })
       } else {
         const handlerPath = (
-          result.experimental.cacheHandlers as {
+          result.cacheHandlers as {
             [handlerName: string]: string | undefined
           }
         )[key]
diff --git a/packages/next/src/server/dev/next-dev-server.ts b/packages/next/src/server/dev/next-dev-server.ts
@@ -761,7 +761,7 @@ export default class DevServer extends Server {
           isAppPath,
           requestHeaders,
           cacheHandler: this.nextConfig.cacheHandler,
-          cacheHandlers: this.nextConfig.experimental.cacheHandlers,
+          cacheHandlers: this.nextConfig.cacheHandlers,
           cacheLifeProfiles: this.nextConfig.cacheLife,
           fetchCacheKeyPrefix: this.nextConfig.experimental.fetchCacheKeyPrefix,
           isrFlushToDisk: this.nextConfig.experimental.isrFlushToDisk,
diff --git a/packages/next/src/server/dev/static-paths-worker.ts b/packages/next/src/server/dev/static-paths-worker.ts
@@ -66,7 +66,7 @@ export async function loadStaticPaths({
   maxMemoryCacheSize?: number
   requestHeaders: IncrementalCache['requestHeaders']
   cacheHandler?: string
-  cacheHandlers?: NextConfigComplete['experimental']['cacheHandlers']
+  cacheHandlers?: NextConfigComplete['cacheHandlers']
   cacheLifeProfiles?: {
     [profile: string]: import('../../server/use-cache/cache-life').CacheLife
   }
diff --git a/packages/next/src/server/route-modules/route-module.ts b/packages/next/src/server/route-modules/route-module.ts
@@ -381,7 +381,7 @@ export abstract class RouteModule<
     nextConfig: NextConfigComplete
   ) {
     if (process.env.NEXT_RUNTIME !== 'edge') {
-      const { cacheHandlers } = nextConfig.experimental
+      const { cacheHandlers } = nextConfig
       if (!cacheHandlers) return
 
       // If we've already initialized the cache handlers interface, don't do it
diff --git a/test/e2e/app-dir/use-cache-custom-handler/next.config.js b/test/e2e/app-dir/use-cache-custom-handler/next.config.js
@@ -3,10 +3,8 @@
  */
 const nextConfig = {
   cacheComponents: true,
-  experimental: {
-    cacheHandlers: {
-      default: require.resolve('./handler.js'),
-    },
+  cacheHandlers: {
+    default: require.resolve('./handler.js'),
   },
 }
 
diff --git a/test/e2e/app-dir/use-cache-unknown-cache-kind/next.config.js b/test/e2e/app-dir/use-cache-unknown-cache-kind/next.config.js
@@ -3,8 +3,8 @@
  */
 const nextConfig = {
   cacheComponents: true,
+  cacheHandlers: {}, // overwrite the default config
   experimental: {
-    cacheHandlers: {}, // overwrite the default config
     prerenderEarlyExit: false,
   },
 }
diff --git a/test/e2e/app-dir/use-cache-unknown-cache-kind/use-cache-unknown-cache-kind.test.ts b/test/e2e/app-dir/use-cache-unknown-cache-kind/use-cache-unknown-cache-kind.test.ts
diff --git a/test/e2e/app-dir/use-cache/next.config.js b/test/e2e/app-dir/use-cache/next.config.js
diff --git a/test/integration/telemetry/next.config.use-cache b/test/integration/telemetry/next.config.use-cache
diff --git a/test/production/custom-server/next.config.js b/test/production/custom-server/next.config.js

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		- x Unknown cache kind "x". Please configure a cache handler for this kind in the `experimental.cacheHandlers` object in your Next.js config.
	`1`	+ x Unknown cache kind "x". Please configure a cache handler for this kind in the `cacheHandlers` object in your Next.js config.
`2`	`2`	`\|`
`3`	`3`	`,-[input.js:1:1]`
`4`	`4`	`1 \| 'use cache: x'`
Original file line number	Diff line number	Diff line change
`@@ -898,5 +898,6 @@`
`898`	`898`	`"897": "Expected HTML document to start with doctype prefix",`
`899`	`899`	"898": "When using Cache Components, all `generateStaticParams` functions must return at least one result. This is to ensure that we can perform build-time validation that there is no other dynamic accesses that would cause a runtime error.\n\nLearn more: https://nextjs.org/docs/messages/empty-generate-static-params",
`900`	`900`	`"899": "Both \"%s\" and \"%s\" files are detected. Please use \"%s\" instead. Learn more: https://nextjs.org/docs/messages/middleware-to-proxy",`
`901`		`- "900": "Both %s file \"./%s\" and %s file \"./%s\" are detected. Please use \"./%s\" only. Learn more: https://nextjs.org/docs/messages/middleware-to-proxy"`
	`901`	`+ "900": "Both %s file \"./%s\" and %s file \"./%s\" are detected. Please use \"./%s\" only. Learn more: https://nextjs.org/docs/messages/middleware-to-proxy",`
	`902`	`+ "901": "Invalid \"cacheHandlers\" provided, expected an object e.g. { default: '/my-handler.js' }, received %s"`
`902`	`903`	`}`
Original file line number	Diff line number	Diff line change
`@@ -124,8 +124,7 @@ export async function collectBuildTraces({`
`124`	`124`	`})`
`125`	`125`	`)`
`126`	`126`
`127`		`- const { cacheHandler } = config`
`128`		`- const { cacheHandlers } = config.experimental`
	`127`	`+ const { cacheHandler, cacheHandlers } = config`
`129`	`128`
`130`	`129`	`// ensure we trace any dependencies needed for custom`
`131`	`130`	`// incremental cache handler`
Original file line number	Diff line number	Diff line change
`@@ -747,7 +747,7 @@ export async function buildAppStaticPaths({`
`747`	`747`	`isrFlushToDisk?: boolean`
`748`	`748`	`fetchCacheKeyPrefix?: string`
`749`	`749`	`cacheHandler?: string`
`750`		`- cacheHandlers?: NextConfigComplete['experimental']['cacheHandlers']`
	`750`	`+ cacheHandlers?: NextConfigComplete['cacheHandlers']`
`751`	`751`	`cacheLifeProfiles?: {`
`752`	`752`	`[profile: string]: import('../../server/use-cache/cache-life').CacheLife`
`753`	`753`	`}`