fortedigital / fortedigital/nextjs-cache-handler
[Next 16] `cacheComponents` and `"use cache"` cacheHandlers configuration and support
- Dominant language
- TypeScript
- Stars
- 187
- Forks
- 29
- PR merge metrics
- No merged PRs in 30d
Description
## 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:
```javascript
// 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:
```typescript
// 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.
## Implementation progress
**Feature branch:** `feature/cache-components`
- [x] Basic research / understanding of the new API
- [x] Setting up a feature branch
- [x] Setting up a test project
- [ ] Redis implementation (this can take a while)
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.