@dictu/nextjs-redis-sentinel-cache-handler

Next.js cache handler backed by ioredis, with support for Redis Sentinel, direct Redis connections, tag revalidation, replica reads, and a filesystem fallback when Redis is unavailable.

Features

• Redis Sentinel support for master/replica setups
• Direct Redis mode for simpler deployments
• Filesystem fallback when Redis is unavailable
• Tag-based invalidation via revalidateTag()
• Circuit breaker to avoid repeated failures during Redis outages

Install

npm install @dictu/nextjs-redis-sentinel-cache-handler ioredis

next is a peer dependency and is expected to already be present in your Next.js app.

Usage

Configure your Next.js app to use the package as its cache handler:

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

Configuration

Sentinel mode

REDIS_SENTINEL_URL=redis://sentinel-1:26379,redis://sentinel-2:26379,redis://sentinel-3:26379
REDIS_SENTINEL_MASTER_NAME=myprimary
REDIS_PASSWORD=your-password
REDIS_CACHE_PREFIX=cache:
REDIS_CACHE_DEBUG_LEVEL=0

Direct Redis mode

REDIS_URL=redis://redis-host:6379
REDIS_PASSWORD=your-password
REDIS_CACHE_PREFIX=cache:
REDIS_CACHE_DEBUG_LEVEL=0

Environment variables

| Variable | Required | Description | | --- | --- | --- | | REDIS_SENTINEL_URL | Sentinel mode | Comma-separated Redis Sentinel URLs. | | REDIS_SENTINEL_MASTER_NAME | No | Sentinel master name. Defaults to myprimary. | | REDIS_URL | Direct mode | Direct Redis connection URL. | | REDIS_PASSWORD | No | Password used for Redis and Sentinel. | | REDIS_CACHE_PREFIX | No | Key prefix. Defaults to cache:. | | REDIS_CACHE_DEBUG_LEVEL | No | 0 = silent, 1 = errors, 2 = warnings, 3 = debug. |

Use either Sentinel mode or direct mode. If neither REDIS_SENTINEL_URL nor REDIS_URL is configured, the handler will fall back to the Next.js filesystem cache only.

Development

npm install
npm run typecheck
npm run build

License

EUPL-1.2