[Next 16] `cacheComponents` and `"use cache"` cacheHandlers configuration and support

[AyronK]

Two Separate Cache Handler Systems

Next.js 16 introduces a critical distinction between two cache handler configurations: cacheHandler (singular) is specifically used for server cache operations like storing and revalidating ISR and route handler responses, while cacheHandlers (plural) is used for the new "use cache" directives.

For Legacy Caching (ISR/Route Handlers)

If you're using custom cache handlers for ISR or route handlers, your existing cacheHandler configuration continues to work:

// next.config.js
module.exports = {
  cacheHandler: require.resolve('./cache-handler.js'),
  cacheMaxMemorySize: 0,
}

This handler can implement methods like get, set, revalidateTag, and resetRequestCache.

For New Cache Components ("use cache")

The new cacheHandlers (plural) configuration allows you to define custom cache storage implementations for "use cache" and "use cache: remote" directives, enabling different caching strategies within the same application:

// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  cacheHandlers: {
    default: './cache-handlers/default-handler.js',
    remote: './cache-handlers/remote-handler.js',
  },
}

New Cache Handler Interface

Cache handlers for "use cache" directives must implement a new CacheHandler interface with methods including get, set, refreshTags, getExpiration, and updateTags. This is different from the older interface and requires adaptation if you're migrating custom handlers.

Migration Path

For Next.js 15 users upgrading to 16:

1. Keep existing cacheHandler for ISR/route handler caching (no changes needed)
2. Add new cacheHandlers configuration if you want to use Cache Components with custom storage
3. Enable Cache Components by adding cacheComponents: true in your next.config.ts

The key distinction is that the old implicit caching system and new explicit Cache Components system run in parallel with separate configuration options.

[AyronK]

Initial implementation attempt has been drafted here #151.

[AyronK]

dynamicParams and revalidate parameters are not supported with the cacheComponents enabled.