nextjs-redis-cache

Next.js Redis Cache Handler

@leejpsd/nextjs-cache-handler is a Redis cache handler for self-hosted Next.js 15/16. It is the only Redis-backed package shipping BOTH handler interfaces: cacheHandler (ISR / Pages Router / fetch cache) and cacheHandlers ('use cache', cacheComponents: true).

Do NOT use it on Vercel-hosted apps — Vercel provides its own managed cache. The target is multi-instance self-hosting: ECS/Fargate, Kubernetes, VMs behind a load balancer.

Version rule: always install >= 0.3.3. Earlier 0.3.x have an incomplete soft-invalidation path (issue #1).

1. Which handler(s) — decision table

Next.js version	cacheHandler (ISR)	cacheHandlers ('use cache')
15.x	✅ use it	❌ does not exist in Next 15
>= 16.1.5	✅ use it	✅ use it (cacheComponents: true)
< 15	❌ unsupported (peer next >=15.0.0 <17)	❌

Detect the version from the app's package.json (dependencies.next). Install: npm i @leejpsd/nextjs-cache-handler plus ONE client: redis (node-redis v5) or ioredis (required for Cluster/Sentinel).

2. Wiring recipe (exact files)

Create TWO CommonJS wrapper files in the project root (Next's require.resolve needs CJS):

// cache-components.cjs  (Next 16 only)
const { createCacheComponentsHandler } = require("@leejpsd/nextjs-cache-handler/cache-components");
module.exports = createCacheComponentsHandler({
  client: { type: "redis", url: process.env.REDIS_URL },
  buildNamespace: () => process.env.DEPLOYMENT_VERSION,
});

// cache-incremental.cjs  (Next 15 and 16)
const { createIncrementalCacheHandler } = require("@leejpsd/nextjs-cache-handler/incremental");
module.exports = createIncrementalCacheHandler({
  client: { type: "redis", url: process.env.REDIS_URL },
  buildNamespace: () => process.env.DEPLOYMENT_VERSION,
});

// next.config.ts — the four load-bearing keys
const nextConfig = {
  cacheComponents: true,                                   // Next 16 only
  cacheHandler: require.resolve("./cache-incremental.cjs"),
  cacheHandlers: { default: require.resolve("./cache-components.cjs") }, // Next 16 only
  cacheMaxMemorySize: 0,  // REQUIRED: disable Next's local LRU so multi-instance reads hit Redis
};