Unverified Commit 212e7b1e authored by Joseph's avatar Joseph Committed by GitHub

docs: replace unbounded cacheHandler snippets and fix tag handling in examples (#100186)

Fixes #100173
parent 7bd26a42
......@@ -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 `'use cache'` 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's tags include the specified tag, delete this entry
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's signature, and the [Redis `cacheHandler` example](https://github.com/vercel/next.js/tree/canary/examples/cache-handler-redis) for a working implementation.
// 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() {}
}
```
For production deployments, the handler must:
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.
- **Store entries where every instance can reach them**, like [Redis](https://github.com/vercel/next.js/tree/canary/examples/cache-handler-redis) or AWS S3. A store inside the process, such as a `Map`, gives each pod its own copy of the cache again.
- **Bound the store'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't serialize and restore on their own. Not handling this serialization results in errors like `segmentData.get is not a function` or `failed to pipe response` on client-side navigation or prefetch (RSC) requests.
- **Index entries by tag.** `APP_PAGE`, `APP_ROUTE`, and `PAGES` entries carry their tags in the `x-next-cache-tags` response header (`data.headers`), while `ctx.tags` carries tags for `fetch` entries. Keep the index in the shared store, so a `revalidateTag` call on one instance invalidates the entry on every instance.
- **Handle storage errors**, such as timeouts and dropped connections.
> **Good to know:**
>
> - `revalidatePath` is a convenience layer on top of cache tags. Calling `revalidatePath` will call the `revalidateTag` function with a special default tag for the provided page.
> - 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.get is not a function` or `failed to pipe response` 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.
> - If you are configuring backends for `'use cache'` directives, use [`cacheHandlers`](/docs/app/api-reference/config/next-config-js/cacheHandlers).
> - Production-oriented community Redis handlers (GET timeouts, in-memory coalescing, multi-instance tag coordination) are listed in the [Redis example README](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).
## Build Cache
......
......@@ -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.
let revalidate = entry.revalidate
for (const tag of entry.tags) {
const { stale = 0, expired = 0 } = tagTimestamps.get(tag) ?? {}
if (expired > entry.timestamp && expired <= Date.now()) {
return undefined
}
if (stale > entry.timestamp) {
revalidate = -1
}
}
// Every hit gets its own stream over the stored bytes
return { ...entry, value: streamFromBytes(entry.value) }
return { ...entry, revalidate, value: streamFromBytes(entry.value) }
},
async set(cacheKey, pendingEntry) {
......@@ -439,20 +463,31 @@ module.exports = {
},
async refreshTags() {
// No-op for in-memory cache
// Tag state lives in this process, so there is nothing to sync
},
async getExpiration(tags) {
// Return 0 to indicate no tags have been revalidated
return 0
return Math.max(
...tags.map((tag) => tagTimestamps.get(tag)?.expired ?? 0),
0
)
},
async updateTags(tags, durations) {
// Implement tag-based invalidation
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)
}
},
}
......@@ -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.
## Platform Support
| Deployment Option | Supported |
......
......@@ -15,7 +15,7 @@ module.exports = {
}
```
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.
## API Reference
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment