---
title: Custom Next.js Cache Handler
description: Configure the Next.js cache used for storing and revalidating data to use any external service like Redis, Memcached, or others.
url: "https://nextjs.org/docs/15/app/api-reference/config/next-config-js/incrementalCacheHandlerPath"
docs_index: /docs/15/llms.txt
lastUpdated: 2025-06-16
navTitle: "cacheHandler"
prerequisites:
  - "Configuration: /docs/15/app/api-reference/config"
  - "next.config.js: /docs/15/app/api-reference/config/next-config-js"
---

> For an index of all documentation, see [/docs/15/llms.txt](/docs/15/llms.txt).

You can configure the Next.js cache location if you want to persist cached pages and data to durable storage, or share the cache across multiple containers or instances of your Next.js application.

```js title="next.config.js"
module.exports = {
  cacheHandler: require.resolve('./cache-handler.js'),
  cacheMaxMemorySize: 0, // disable default in-memory caching
}
```

View an example of a [custom cache handler](/docs/app/guides/self-hosting#configuring-caching) and learn more about the implementation.

## API Reference

The cache handler can implement the following methods: `get`, `set`, `revalidateTag`, and `resetRequestCache`.

### `get()`

| Parameter | Type     | Description                  |
| --------- | -------- | ---------------------------- |
| `key`     | `string` | The key to the cached value. |

Cache keys are opaque identifiers. Preserve the entire key when reading and writing entries; a key is not a request pathname.

Response keys include the response kind and a SHA-256 hash of the source route to keep different routes from sharing entries. Pages Router sources use the route definition's canonical `pathname`, so an index module has the same identity in both bundlers. App Router sources use the full `page` module name, including route groups and parallel slots. For example, a Pages Router response for `/blog/post` generated by `/blog/[slug]` uses `/route-cache/PAGES/<route-hash>/$/blog/post`, where `<route-hash>` is the 64-character hexadecimal SHA-256 digest of the UTF-8 source string `/blog/[slug]`. This bounds the added directory depth and avoids expanding Unicode source names on disk. The request pathname remains readable; the source route cannot be recovered from its hash. Handlers that previously interpreted keys as pathnames must account for this namespace. Fetch cache keys are unchanged.

Without a build adapter, prerendered responses remain at their historical `server/pages` and `server/app` paths. Their metadata identifies the exact scoped key, source owner, and fallback status that produced each immutable build seed. The built-in filesystem cache verifies that metadata before reading a historical seed, then promotes the complete response to `server/route-cache` while retaining the original artifact and its age. When an adapter is configured, build-time response artifacts are written directly to their scoped `server/route-cache` keys so colliding routes cannot overwrite one another before the adapter packages them. Static `output: 'export'` continues to emit normal public export files. Runtime reads and writes use only scoped keys. Custom cache handlers receive the opaque scoped key and are never queried with a historical pathname; an external response cache must preserve that key unchanged.

Runtime packaging must preserve the existing source-route metadata in the prerender manifest. Next.js also uses it to verify the allowed parameters and rendering mode of the selected route.

Integrations that read cached responses before invoking Next.js must also preserve source-route ownership when selecting entries. Removing the route namespace or falling back to pathname-only cache entries defeats that isolation.

Returns the cached value or `null` if not found.

### `set()`

| Parameter | Type           | Description                      |
| --------- | -------------- | -------------------------------- |
| `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>`.

### `revalidateTag()`

| Parameter | Type                   | Description                   |
| --------- | ---------------------- | ----------------------------- |
| `tag`     | `string` or `string[]` | The cache tags to revalidate. |

Returns `Promise<void>`. Learn more about [revalidating data](/docs/app/guides/incremental-static-regeneration) or the [`revalidateTag()`](/docs/app/api-reference/functions/revalidateTag) function.

### `resetRequestCache()`

This method resets the temporary in-memory cache for a single request before the next request.

Returns `void`.

**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.

## Platform Support

| Deployment Option                                                   | Supported         |
| ------------------------------------------------------------------- | ----------------- |
| [Node.js server](/docs/app/getting-started/deploying#nodejs-server) | Yes               |
| [Docker container](/docs/app/getting-started/deploying#docker)      | Yes               |
| [Static export](/docs/app/getting-started/deploying#static-export)  | No                |
| [Adapters](/docs/app/getting-started/deploying#adapters)            | Platform-specific |

Learn how to [configure ISR](/docs/app/guides/self-hosting#caching-and-isr) when self-hosting Next.js.

## Version History

| Version   | Changes                                                      |
| --------- | ------------------------------------------------------------ |
| `v14.1.0` | Renamed to `cacheHandler` and became stable.                 |
| `v13.4.0` | `incrementalCacheHandlerPath` support for `revalidateTag`.   |
| `v13.4.0` | `incrementalCacheHandlerPath` support for standalone output. |
| `v12.2.0` | Experimental `incrementalCacheHandlerPath` added.            |

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/docs/15/llms.txt](/docs/15/llms.txt)