Stabilize custom cache handlers and changing memory size.

docs/02-app/01-building-your-application/09-deploying/index.mdx

@@ -146,10 +146,8 @@ To configure the ISR/Data Cache location when self-hosting, you can configure a
 
 ```jsx filename="next.config.js"
 module.exports = {
-  experimental: {
-    incrementalCacheHandlerPath: require.resolve('./cache-handler.js'),
-    isrMemoryCacheSize: 0, // disable default in-memory caching
-  },
+  cacheHandler: require.resolve('./cache-handler.js'),
+  cacheMaxMemorySize: 0, // disable default in-memory caching
 }
 ```
 

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

@@ -1,41 +1,19 @@
 ---
-title: incrementalCacheHandlerPath
-description: Configure the Next.js cache used for storing and revalidating data.
+title: Custom Next.js Cache Handler
+nav_title: cacheHandler
+description: Configure the Next.js cache used for storing and revalidating data to use any external service like Redis, Memcached, or others.
 ---
 
-In Next.js, the [default cache handler](/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating) uses the filesystem cache. This requires no configuration, however, you can customize the cache handler by using the `incrementalCacheHandlerPath` field in `next.config.js`.
+In Next.js, the [default cache handler](/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating) for the Pages and App Router uses the filesystem cache. This requires no configuration, however, you can customize the cache handler by using the `cacheHandler` field in `next.config.js`.
 
 ```js filename="next.config.js"
 module.exports = {
-  experimental: {
-    incrementalCacheHandlerPath: require.resolve('./cache-handler.js'),
-  },
+  cacheHandler: require.resolve('./cache-handler.js'),
+  cacheMaxMemorySize: 0, // disable default in-memory caching
 }
 ```
 
-Here's an example of a custom cache handler:
-
-```js filename="cache-handler.js"
-const cache = new Map()
-
-module.exports = class CacheHandler {
-  constructor(options) {
-    this.options = options
-    this.cache = {}
-  }
-
-  async get(key) {
-    return cache.get(key)
-  }
-
-  async set(key, data) {
-    cache.set(key, {
-      value: data,
-      lastModified: Date.now(),
-    })
-  }
-}
-```
+View an example of a [custom cache handler](/docs/app/building-your-application/deploying#configuring-caching) and learn more about implementation.
 
 ## API Reference
 
@@ -55,6 +33,7 @@ Returns the cached value or `null` if not found.
 | --------- | -------------- | -------------------------------- |
 | `key`     | `string`       | The key to store the data under. |
 | `data`    | Data or `null` | The data to be cached.           |
+| `ctx`     | `{ tags: [] }` | The cache tags provided.         |
 
 Returns `Promise<void>`.
 
@@ -65,3 +44,16 @@ Returns `Promise<void>`.
 | `tag`     | `string` | The cache tag to revalidate. |
 
 Returns `Promise<void>`. Learn more about [revalidating data](/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating) or the [`revalidateTag()`](/docs/app/api-reference/functions/revalidateTag) function.
+
+**Good to know:**
+
+- `revalidatePath` is a convenience layer on top of cache tags. Calling `revalidatePath` will call your `revalidateTag` function, which you can then choose if you want to tag cache keys based on the path.
+
+## Version History
+
+| Version   | Changes                                                                  |
+| --------- | ------------------------------------------------------------------------ |
+| `v14.1.0` | Renamed `cacheHandler` is stable.                                        |
+| `v13.4.0` | `incrementalCacheHandlerPath` (experimental) supports `revalidateTag`.   |
+| `v13.4.0` | `incrementalCacheHandlerPath` (experimental) supports standalone output. |
+| `v12.2.0` | `incrementalCacheHandlerPath` (experimental) is added.                   |

docs/03-pages/01-building-your-application/03-data-fetching/04-incremental-static-regeneration.mdx

@@ -1,6 +1,6 @@
 ---
-title: Incremental Static Regeneration
-description: 'Learn how to create or update static pages at runtime with Incremental Static Regeneration.'
+title: Incremental Static Regeneration (ISR)
+description: Learn how to create or update static pages at runtime with Incremental Static Regeneration.
 ---
 
 <details>
@@ -169,29 +169,13 @@ export async function getStaticProps() {
 
 Incremental Static Regeneration (ISR) works on [self-hosted Next.js sites](/docs/pages/building-your-application/deploying#self-hosting) out of the box when you use `next start`.
 
-You can use this approach when deploying to container orchestrators such as [Kubernetes](https://kubernetes.io/) or [HashiCorp Nomad](https://www.nomadproject.io/). By default, generated assets will be stored in-memory on each pod. This means that each pod will have its own copy of the static files. Stale data may be shown until that specific pod is hit by a request.
-
-To ensure consistency across all pods, you can disable in-memory caching. This will inform the Next.js server to only leverage assets generated by ISR in the file system.
-
-You can use a shared network mount in your Kubernetes pods (or similar setup) to reuse the same file-system cache between different containers. By sharing the same mount, the `.next` folder which contains the `next/image` cache will also be shared and re-used.
-
-To disable in-memory caching, set `isrMemoryCacheSize` to `0` in your `next.config.js` file:
-
-```js filename="next.config.js"
-module.exports = {
-  experimental: {
-    // Defaults to 50MB
-    isrMemoryCacheSize: 0, // cache size in bytes
-  },
-}
-```
-
-> **Good to know**: You might need to consider a race condition between multiple pods trying to update the cache at the same time, depending on how your shared mount is configured.
+Learn more about [self-hosting Next.js](/docs/pages/building-your-application/deploying#self-hosting).
 
 ## Version History
 
 | Version   | Changes                                                                                 |
 | --------- | --------------------------------------------------------------------------------------- |
+| `v14.1.0` | Custom `cacheHandler` is stable.                                                        |
 | `v12.2.0` | On-Demand ISR is stable                                                                 |
 | `v12.1.0` | On-Demand ISR added (beta).                                                             |
 | `v12.0.0` | [Bot-aware ISR fallback](https://nextjs.org/blog/next-12#bot-aware-isr-fallback) added. |

packages/next/src/build/collect-build-traces.ts

@@ -239,16 +239,16 @@ export async function collectBuildTraces({
             )),
       ]
 
-      const { incrementalCacheHandlerPath } = config.experimental
+      const { cacheHandler } = config
 
       // ensure we trace any dependencies needed for custom
       // incremental cache handler
-      if (incrementalCacheHandlerPath) {
+      if (cacheHandler) {
         sharedEntriesSet.push(
           require.resolve(
-            path.isAbsolute(incrementalCacheHandlerPath)
-              ? incrementalCacheHandlerPath
-              : path.join(dir, incrementalCacheHandlerPath)
+            path.isAbsolute(cacheHandler)
+              ? cacheHandler
+              : path.join(dir, cacheHandler)
           )
         )
       }

packages/next/src/build/entries.ts

@@ -414,8 +414,7 @@ export function getEdgeServerEntry(opts: {
     pagesType: opts.pagesType,
     appDirLoader: Buffer.from(opts.appDirLoader || '').toString('base64'),
     sriEnabled: !opts.isDev && !!opts.config.experimental.sri?.algorithm,
-    incrementalCacheHandlerPath:
-      opts.config.experimental.incrementalCacheHandlerPath,
+    cacheHandler: opts.config.cacheHandler,
     preferredRegion: opts.preferredRegion,
     middlewareConfig: Buffer.from(
       JSON.stringify(opts.middlewareConfig || {})

packages/next/src/build/index.ts

@@ -1245,7 +1245,7 @@ export default async function build(
         PAGES_MANIFEST
       )
 
-      const { incrementalCacheHandlerPath } = config.experimental
+      const { cacheHandler } = config
 
       const requiredServerFilesManifest = nextBuildSpan
         .traceChild('generate-required-server-files')
@@ -1260,12 +1260,12 @@ export default async function build(
                     compress: false,
                   }
                 : {}),
+              // cacheHandler: cacheHandler
+              //   ? path.relative(distDir, cacheHandler)
+              //   : undefined,
               experimental: {
                 ...config.experimental,
                 trustHostHeader: ciEnvironment.hasNextSupport,
-                incrementalCacheHandlerPath: incrementalCacheHandlerPath
-                  ? path.relative(distDir, incrementalCacheHandlerPath)
-                  : undefined,
 
                 // @ts-expect-error internal field TODO: fix this, should use a separate mechanism to pass the info.
                 isExperimentalCompile: isCompileMode,
@@ -1523,11 +1523,11 @@ export default async function build(
 
       if (config.experimental.staticWorkerRequestDeduping) {
         let CacheHandler
-        if (incrementalCacheHandlerPath) {
+        if (cacheHandler) {
           CacheHandler = interopDefault(
-            await import(
-              formatDynamicImportPath(dir, incrementalCacheHandlerPath)
-            ).then((mod) => mod.default || mod)
+            await import(formatDynamicImportPath(dir, cacheHandler)).then(
+              (mod) => mod.default || mod
+            )
           )
         }
 
@@ -1542,7 +1542,7 @@ export default async function build(
             : config.experimental.isrFlushToDisk,
           serverDistDir: path.join(distDir, 'server'),
           fetchCacheKeyPrefix: config.experimental.fetchCacheKeyPrefix,
-          maxMemoryCacheSize: config.experimental.isrMemoryCacheSize,
+          maxMemoryCacheSize: config.cacheMaxMemorySize,
           getPrerenderManifest: () => ({
             version: -1 as any, // letting us know this doesn't conform to spec
             routes: {},
@@ -1840,13 +1840,11 @@ export default async function build(
                             pageRuntime,
                             edgeInfo,
                             pageType,
-                            incrementalCacheHandlerPath:
-                              config.experimental.incrementalCacheHandlerPath,
+                            cacheHandler: config.cacheHandler,
                             isrFlushToDisk: ciEnvironment.hasNextSupport
                               ? false
                               : config.experimental.isrFlushToDisk,
-                            maxMemoryCacheSize:
-                              config.experimental.isrMemoryCacheSize,
+                            maxMemoryCacheSize: config.cacheMaxMemorySize,
                             nextConfigOutput: config.output,
                             ppr: config.experimental.ppr === true,
                           })

packages/next/src/build/utils.ts

@@ -1304,8 +1304,8 @@ export async function buildAppStaticPaths({
   configFileName,
   generateParams,
   isrFlushToDisk,
-  incrementalCacheHandlerPath,
   requestHeaders,
+  cacheHandler,
   maxMemoryCacheSize,
   fetchCacheKeyPrefix,
   ppr,
@@ -1315,10 +1315,10 @@ export async function buildAppStaticPaths({
   page: string
   configFileName: string
   generateParams: GenerateParamsResults
-  incrementalCacheHandlerPath?: string
   distDir: string
   isrFlushToDisk?: boolean
   fetchCacheKeyPrefix?: string
+  cacheHandler?: string
   maxMemoryCacheSize?: number
   requestHeaders: IncrementalCache['requestHeaders']
   ppr: boolean
@@ -1328,11 +1328,11 @@ export async function buildAppStaticPaths({
 
   let CacheHandler: any
 
-  if (incrementalCacheHandlerPath) {
+  if (cacheHandler) {
     CacheHandler = interopDefault(
-      await import(
-        formatDynamicImportPath(dir, incrementalCacheHandlerPath)
-      ).then((mod) => mod.default || mod)
+      await import(formatDynamicImportPath(dir, cacheHandler)).then(
+        (mod) => mod.default || mod
+      )
     )
   }
 
@@ -1483,7 +1483,7 @@ export async function isPageStatic({
   originalAppPath,
   isrFlushToDisk,
   maxMemoryCacheSize,
-  incrementalCacheHandlerPath,
+  cacheHandler,
   ppr,
 }: {
   dir: string
@@ -1501,7 +1501,7 @@ export async function isPageStatic({
   originalAppPath?: string
   isrFlushToDisk?: boolean
   maxMemoryCacheSize?: number
-  incrementalCacheHandlerPath?: string
+  cacheHandler?: string
   nextConfigOutput: 'standalone' | 'export'
   ppr: boolean
 }): Promise<{
@@ -1667,7 +1667,7 @@ export async function isPageStatic({
             requestHeaders: {},
             isrFlushToDisk,
             maxMemoryCacheSize,
-            incrementalCacheHandlerPath,
+            cacheHandler,
             ppr,
             ComponentMod,
           }))

packages/next/src/build/webpack/loaders/next-edge-ssr-loader/index.ts

@@ -24,7 +24,7 @@ export type EdgeSSRLoaderQuery = {
   appDirLoader?: string
   pagesType: PAGE_TYPES
   sriEnabled: boolean
-  incrementalCacheHandlerPath?: string
+  cacheHandler?: string
   preferredRegion: string | string[] | undefined
   middlewareConfig: string
   serverActions?: {
@@ -76,7 +76,7 @@ const edgeSSRLoader: webpack.LoaderDefinitionFunction<EdgeSSRLoaderQuery> =
       appDirLoader: appDirLoaderBase64,
       pagesType,
       sriEnabled,
-      incrementalCacheHandlerPath,
+      cacheHandler,
       preferredRegion,
       middlewareConfig: middlewareConfigBase64,
       serverActions,
@@ -158,7 +158,7 @@ const edgeSSRLoader: webpack.LoaderDefinitionFunction<EdgeSSRLoaderQuery> =
               : JSON.stringify(serverActions),
         },
         {
-          incrementalCacheHandler: incrementalCacheHandlerPath ?? null,
+          incrementalCacheHandler: cacheHandler ?? null,
         }
       )
     } else {
@@ -187,7 +187,7 @@ const edgeSSRLoader: webpack.LoaderDefinitionFunction<EdgeSSRLoaderQuery> =
         },
         {
           userland500Page: userland500Path,
-          incrementalCacheHandler: incrementalCacheHandlerPath ?? null,
+          incrementalCacheHandler: cacheHandler ?? null,
         }
       )
     }

packages/next/src/export/helpers/create-incremental-cache.ts

@@ -8,17 +8,17 @@ import { interopDefault } from '../../lib/interop-default'
 import { formatDynamicImportPath } from '../../lib/format-dynamic-import-path'
 
 export async function createIncrementalCache({
-  incrementalCacheHandlerPath,
-  isrMemoryCacheSize,
+  cacheHandler,
+  cacheMaxMemorySize,
   fetchCacheKeyPrefix,
   distDir,
   dir,
   enabledDirectories,
   experimental,
   flushToDisk,
 }: {
-  incrementalCacheHandlerPath?: string
-  isrMemoryCacheSize?: number
+  cacheHandler?: string
+  cacheMaxMemorySize?: number
   fetchCacheKeyPrefix?: string
   distDir: string
   dir: string
@@ -28,11 +28,11 @@ export async function createIncrementalCache({
 }) {
   // Custom cache handler overrides.
   let CacheHandler: any
-  if (incrementalCacheHandlerPath) {
+  if (cacheHandler) {
     CacheHandler = interopDefault(
-      await import(
-        formatDynamicImportPath(dir, incrementalCacheHandlerPath)
-      ).then((mod) => mod.default || mod)
+      await import(formatDynamicImportPath(dir, cacheHandler)).then(
+        (mod) => mod.default || mod
+      )
     )
   }
 
@@ -41,7 +41,7 @@ export async function createIncrementalCache({
     requestHeaders: {},
     flushToDisk,
     fetchCache: true,
-    maxMemoryCacheSize: isrMemoryCacheSize,
+    maxMemoryCacheSize: cacheMaxMemorySize,
     fetchCacheKeyPrefix,
     getPrerenderManifest: () => ({
       version: 4,

packages/next/src/export/index.ts

@@ -701,11 +701,10 @@ export async function exportAppImpl(
           parentSpanId: pageExportSpan.getId(),
           httpAgentOptions: nextConfig.httpAgentOptions,
           debugOutput: options.debugOutput,
-          isrMemoryCacheSize: nextConfig.experimental.isrMemoryCacheSize,
+          cacheMaxMemorySize: nextConfig.cacheMaxMemorySize,
           fetchCache: true,
           fetchCacheKeyPrefix: nextConfig.experimental.fetchCacheKeyPrefix,
-          incrementalCacheHandlerPath:
-            nextConfig.experimental.incrementalCacheHandlerPath,
+          cacheHandler: nextConfig.cacheHandler,
           enableExperimentalReact: needsExperimentalReact(nextConfig),
           enabledDirectories,
         })

packages/next/src/export/types.ts

@@ -53,9 +53,9 @@ export interface ExportPageInput {
   parentSpanId: any
   httpAgentOptions: NextConfigComplete['httpAgentOptions']
   debugOutput?: boolean
-  isrMemoryCacheSize?: NextConfigComplete['experimental']['isrMemoryCacheSize']
+  cacheMaxMemorySize?: NextConfigComplete['cacheMaxMemorySize']
   fetchCache?: boolean
-  incrementalCacheHandlerPath?: string
+  cacheHandler?: string
   fetchCacheKeyPrefix?: string
   nextConfigOutput?: NextConfigComplete['output']
   enableExperimentalReact?: boolean