@@ -108,9 +108,7 @@ If you want to host static assets on a different domain or CDN, you can use the
By default, generated cache assets will be stored in memory (defaults to 50mb) and on disk. On ephemeral compute platforms (common serverless setups), local disk is often non-persistent or unavailable, so this cache is effectively short-lived and per-instance. If you are hosting Next.js using a container orchestration platform like Kubernetes, each pod will have a copy of the cache. To prevent stale data from being shown since the cache is not shared between pods by default, you can configure the Next.js cache to provide a cache handler and disable in-memory caching.
To configure the cache location when self-hosting, you can configure a custom handler in your `next.config.js` file:
For production deployments, use this as a starting point and extend it with durable storage, eviction policies, error handling, and distributed tag coordination. See [Custom Next.js Cache Handler](/docs/app/api-reference/config/next-config-js/incrementalCacheHandlerPath) and the [Redis `cacheHandler` example](https://github.com/vercel/next.js/tree/canary/examples/cache-handler-redis). If you are configuring backends for `'usecache'` directives, use [`cacheHandlers`](/docs/app/api-reference/config/next-config-js/cacheHandlers).
To configure the cache location when self-hosting, set a custom handler in your `next.config.js` file:
```jsx filename="next.config.js"
module.exports = {
...
...
@@ -119,55 +117,20 @@ module.exports = {
}
```
Then, create `cache-handler.js` in the root of your project, for example:
```jsx filename="cache-handler.js"
const cache = new Map()
module.exports = class CacheHandler {
constructor(options) {
this.options = options
}
async get(key) {
// This could be stored anywhere, like durable storage
return cache.get(key)
}
async set(key, data, ctx) {
// This could be stored anywhere, like durable storage
cache.set(key, {
value: data,
lastModified: Date.now(),
tags: ctx.tags,
})
}
async revalidateTag(tags) {
// tags is either a string or an array of strings
tags = [tags].flat()
// Iterate over all entries in the cache
for (let [key, value] of cache) {
// If the value'stagsincludethespecifiedtag,deletethisentry
if(value.tags.some((tag)=>tags.includes(tag))){
cache.delete(key)
}
}
}
The handler file exports a class that implements `get`, `set`, `revalidateTag`, and `resetRequestCache`. See [`cacheHandler`](/docs/app/api-reference/config/next-config-js/incrementalCacheHandlerPath) for each method'ssignature,andthe[Redis`cacheHandler`example](https://github.com/vercel/next.js/tree/canary/examples/cache-handler-redis)foraworkingimplementation.
// If you want to have temporary in memory cache for a single request that is reset
// before the next request you can leverage this method
resetRequestCache(){}
}
```
Forproductiondeployments,thehandlermust:
Using a custom cache handler will allow you to ensure consistency across all pods hosting your Next.js application. For instance, you can save the cached values anywhere, like [Redis](https://github.com/vercel/next.js/tree/canary/examples/cache-handler-redis) or AWS S3.
-**Boundthestore's size.** Use a TTL or size-based eviction to remove entries for paths and `fetch` keys that are no longer requested.
- **Serialize entries.** Any store outside the process needs this. An entry can contain `Buffer` (for example `rscData`) and `Map` (for example `segmentData`) values that `JSON.stringify`/`JSON.parse` can'tserializeandrestoreontheirown.Nothandlingthisserializationresultsinerrorslike`segmentData.get is not a function`or`failed to pipe response`onclient-sidenavigationorprefetch(RSC)requests.
> - The example above keeps entries in memory. A handler backed by durable storage (like the [Redis example](https://github.com/vercel/next.js/tree/canary/examples/cache-handler-redis)) must serialize entries itself, and an entry can contain `Buffer` (for example `rscData`) and `Map` (for example `segmentData`) values that `JSON.stringify`/`JSON.parse` can't serialize and restore on their own. Not handling this serialization results in errors like `segmentData.getisnotafunction` or `failedtopiperesponse` on client-side navigation or prefetch (RSC) requests.
> - When indexing entries for `revalidateTag`, read cache tags from the right place: `APP_PAGE`, `APP_ROUTE`, and `PAGES` entries carry them in the `x-next-cache-tags` response header (`data.headers`), while `ctx.tags` carries tags for `fetch` entries.
>-Production-orientedcommunityRedishandlers(GETtimeouts,in-memorycoalescing,multi-instancetagcoordination)arelistedinthe[RedisexampleREADME](https://github.com/vercel/next.js/blob/canary/examples/cache-handler-redis/README.md#production-community-handlers), including [`@trieb.work/nextjs-turbo-redis-cache`](https://github.com/trieb-work/nextjs-turbo-redis-cache) and [`@mrjasonroy/cache-components-cache-handler`](https://github.com/mrjasonroy/cache-components-cache-handler).
@@ -284,16 +284,25 @@ Whether `durations` is present tells you which kind of invalidation this is:
Returns `Promise<void>`.
When tags are revalidated, your handler should invalidate all cache entries that have any of those tags. Iterate through your cache and remove entries whose tags match the provided list.
Your handler should record when each tag was invalidated. [`get()`](#get) compares those times against an entry's `timestamp`, and [`getExpiration()`](#getexpiration) does the same for [soft tags](#soft-tags). Soft tags are not stored in an entry's `tags`, so deleting the entries that carry a tag does not cover [`revalidatePath()`](/docs/app/api-reference/functions/revalidatePath).
```js
const cacheHandler = {
async updateTags(tags, durations) {
// Invalidate all cache entries with matching tags
for (const [key, entry] of cache.entries()) {
if (entry.tags.some((tag) => tags.includes(tag))) {
cache.delete(key)
const now = Date.now()
for (const tag of tags) {
const timestamps = tagTimestamps.get(tag) ?? {}
if (durations) {
// Serve while refreshing, and expire after `durations.expire` seconds
timestamps.stale = now
if (durations.expire !== undefined) {
timestamps.expired = now + durations.expire * 1000
}
} else {
// Expire immediately
timestamps.expired = now
}
tagTimestamps.set(tag, timestamps)
}
},
}
...
...
@@ -375,14 +384,18 @@ Cache operations should be implemented defensively:
## Examples
### Basic in-memory cache handler
The examples below show how a handler meets the API contract. They leave out the eviction, error handling, and multi-instance coordination that a production handler must add. The [`cache-handler-redis` example](https://github.com/vercel/next.js/tree/canary/examples/cache-handler-redis) is a fuller Redis implementation of both cache APIs, and its README lists community handlers that cover more cases.
### In-memory handler for learning and debugging
Here's a minimal implementation using a `Map` for storage. This example demonstrates the core concepts, but for a production-ready implementation with LRU eviction, error handling, and tag management, see the [default cache handler](https://github.com/vercel/next.js/blob/canary/packages/next/src/server/lib/cache-handlers/default.ts).
This handler keeps entries in a `Map`, which makes it a place to log or inspect what Next.js stores and how tags invalidate it. It runs per process and has no eviction. The [built-in handler](https://github.com/vercel/next.js/blob/canary/packages/next/src/server/lib/cache-handlers/default.ts) is also in memory, and adds a size-bounded LRU and error handling.
```js filename="cache-handlers/memory-handler.js"
// Entries hold the serialized bytes, never the stream they arrived on
const cache = new Map()
const pendingSets = new Map()
// Tag invalidation times in milliseconds: { stale, expired }
const tagTimestamps = new Map()
function streamFromBytes(bytes) {
return new ReadableStream({
...
...
@@ -407,10 +420,21 @@ module.exports = {
}
// No age check: Next.js compares `timestamp` against `expire` itself.
// Soft tags are checked by Next.js through `getExpiration()`.
// This `Map` also has no eviction, which a real handler needs.
if (entry.tags.some((tag) => tags.includes(tag))) {
cache.delete(key)
const now = Date.now()
for (const tag of tags) {
const timestamps = tagTimestamps.get(tag) ?? {}
if (durations) {
// Serve while refreshing, and expire after `durations.expire` seconds
timestamps.stale = now
if (durations.expire !== undefined) {
timestamps.expired = now + durations.expire * 1000
}
} else {
// Expire immediately
timestamps.expired = now
}
tagTimestamps.set(tag, timestamps)
}
},
}
...
...
@@ -460,7 +495,7 @@ module.exports = {
### External storage pattern
For durable storage like Redis or a database, you'll need to serialize the cache entries. Here's a simple Redis example:
A handler backed by Redis or a database must serialize each entry. Drain the stream in `set()`, and rebuild one from the stored bytes in `get()`:
```js filename="cache-handlers/redis-handler.js"
const { createClient } = require('redis')
...
...
@@ -532,26 +567,11 @@ module.exports = {
)
},
async refreshTags() {
// No-op for basic Redis implementation
// Could sync with external tag service if needed
},
async getExpiration(tags) {
// Return 0 to indicate no tags have been revalidated
// Could query Redis for tag expiration timestamps if tracking them
return 0
},
async updateTags(tags, durations) {
// Implement tag-based invalidation if needed
// Could iterate over keys with matching tags and delete them
},
// refreshTags(), getExpiration(), and updateTags() also need shared state.
// See Distributed Tag Coordination for that half of the handler.
}
```
A complete Redis wiring of both cache APIs lives in the [`cache-handler-redis` example](https://github.com/vercel/next.js/tree/canary/examples/cache-handler-redis). Production community handlers are listed in that example's README.
View an example of a [custom cache handler](/docs/app/guides/self-hosting#configuring-caching) and learn more about the implementation.
See the [Redis `cacheHandler` example](https://github.com/vercel/next.js/tree/canary/examples/cache-handler-redis) for a working implementation, and [Configuring Caching](/docs/app/guides/self-hosting#configuring-caching) for what a handler backed by a shared store needs.