Custom Next.js Cache Handler

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.

Good to know: The cacheHandler (singular) configuration is specifically used by Next.js for server cache operations such as storing and revalidating ISR, route handler responses, and optimized images. It is not used by 'use cache' directives. For 'use cache' directives, use cacheHandlers (plural) instead.

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

View an example of a custom cache handler and learn more about the implementation.

API Reference

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

get()

The ctx parameter contains a kind property that indicates the type of cache entry being retrieved. Possible values include 'APP_PAGE', 'APP_ROUTE', 'PAGES', 'FETCH', and 'IMAGE'.

Returns the cached value or null if not found.

set()

The data object contains a kind property that indicates the type of cache entry. For image optimization, kind will be 'IMAGE' and the data will include properties like buffer, etag, extension, and revalidate.

Returns Promise<void>.

revalidateTag()

Returns Promise<void>. Learn more about revalidating data or the 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.

Image Optimization Caching

The cacheHandler can also be used for caching optimized images from next/image. To enable this, set images.customCacheHandler to true in your next.config.js:

module.exports = {
  cacheHandler: require.resolve('./cache-handler.js'),
  images: {
    customCacheHandler: true,
  },
}

Good to know: This opt-in flag will become the default behavior in the next major version. Setting it now allows you to prepare your cache handler for image optimization entries.

You can use the kind property to differentiate between cache entry types and handle images separately if needed, for example to implement an eviction policy or store images in a different location.

When handling image cache entries, the kind will be 'IMAGE' and the data will include buffer, etag, extension, and revalidate properties.

Platform Support

Learn how to configure ISR when self-hosting Next.js.

Version History