fortedigital / fortedigital/nextjs-cache-handler

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

Open
#152 13 comments 0 reactions 0 assignees View on GitHub
3.0.0 candidate | Next 16 enhancement help wanted
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.