DEV Community

zisam shaikh
zisam shaikh

Posted on Edited on

Next.js 15 Custom Cache Handler: Self-Host ISR with L1 RAM + L2 Redis & Stop Cache Stampedes

If you self-host Next.js 15 on Docker, Kubernetes, Railway, Coolify, or Fly.io, you quickly run into two production caching challenges:

  1. Multi-Instance Cache Desync: By default, Next.js stores ISR and App Router fetch caches on the local container filesystem/memory, meaning Pod A and Pod B serve inconsistent data after revalidateTag().
  2. The ISR Cache Stampede (Thundering Herd): When a high-traffic cached route or query expires under 1,000 req/sec, dozens of concurrent requests trigger expensive regeneration queries against your database at the exact same millisecond.

To solve both problems with zero runtime dependencies in the core engine, we built KVDock โ€” featuring a drop-in Next.js 15 Incremental Cache Handler, multi-tier L1/L2 caching with KVDockBus cross-pod invalidation, and single-flight stampede coalescing.

๐ŸŽฎ Launch the Live Browser Stampede Simulator โ€” Simulate 5,000 concurrent cache misses in your browser!

โญ Support open-source: Give KVDock a โ˜… Star on GitHub (We are just 13 stars away from our first 16-star community milestone!)


โšก What Happens During a Cache Stampede?

Imagine a popular product page cache expires while 1,000 concurrent users load it simultaneously:

Metric Standard Uncoalesced Cache kvdock.getOrSet() (Single-Flight) Impact
Concurrent Requests 1,000 1,000 Identical load
Database Queries Executed 1,000 queries (Thundering Herd) 1 query (Single-Flight) 99.9% DB load reduction
Coalesced Callers 0 999 Zero lock contention

๐Ÿ› ๏ธ Next.js 15 Custom cacheHandler Setup

First, install kvdock:

npm install kvdock
Enter fullscreen mode Exit fullscreen mode

Create cache-handler.mjs in your project root (using createNextCacheHandler or subclassing KVDockNextCacheHandler from kvdock/integrations/nextjs):

// cache-handler.mjs
import { KVDockNextCacheHandler, createNextCacheHandler } from "kvdock/integrations/nextjs";
import { TieredDock } from "kvdock";
import { MemoryAdapter } from "kvdock/adapters/memory";
import { RedisAdapter } from "kvdock/adapters/redis";

const dock = new TieredDock({
  l1: new MemoryAdapter({ maxSize: 5_000 }),
  l2: new RedisAdapter({ client: redisClient }),
  l1TTL: 60_000,       // 1 minute hot in-process L1 cache
  defaultTTL: 3600_000 // 1 hour shared Redis L2 cache
});

export default createNextCacheHandler({ dock });
Enter fullscreen mode Exit fullscreen mode

Note for kvdock <= 0.3.2 prior to bf8f1c: Next.js passes its runtime ctx ({ serverDistDir, maxMemoryCacheSize, ... }) to new CacheHandler(ctx). On 0.3.2, subclassing export default class CacheHandler extends KVDockNextCacheHandler { constructor() { super({ dock }); } } ensures Next's ctx argument is handled cleanly (fixed natively in createNextCacheHandler on main โ€” huge thanks to @sunnatulla_dev for catching this!).

Then wire up cache-handler.mjs in next.config.mjs:

/** @type {import("next").NextConfig} */
const nextConfig = {
  cacheHandler: import.meta.resolve("./cache-handler.mjs"),
  cacheMaxMemorySize: 0, // Let KVDock TieredDock manage L1 RAM + L2 Redis/SQLite
};

export default nextConfig;
Enter fullscreen mode Exit fullscreen mode

๐Ÿ”„ Cross-Pod L1 Cache Invalidation with KVDockBus

How does Pod B evict its in-memory L1 cache when Pod A calls revalidateTag("products")?

TieredDock accepts a bus option (KVDockBus from kvdock/bus, such as RedisPubSubBus or BroadcastChannelBus). When invalidateTag(tag) is called on Pod A:

  1. TieredDock resolves the tagged keys and purges both L1 and L2.
  2. It publishes a { type: "tag_invalidation", tag, keys } event over the bus.
  3. All other pods subscribed to the bus immediately evict those keys from their local L1 memory cacheโ€”so L1 stays sub-millisecond fast without serving stale data across pods!

๐Ÿงช Try the Interactive Playground & Star on GitHub!

If you find this useful or want to bookmark it for your next Next.js / TypeScript project, please drop a โ˜… Star on GitHub!

Top comments (1)

Collapse
 
sunnatulla_dev profile image
Sunnatulla •

Tried the setup from the post against kvdock 0.3.2 from npm and hit a few things before it got anywhere near Next.

import.meta.resolve("kvdock/next") throws ERR_PACKAGE_PATH_NOT_EXPORTED, there's no ./next in the exports map. The handler lives at kvdock/integrations/nextjs. But that module has no default export either, only KVDockNextCacheHandler and createNextCacheHandler, and Next expects the cacheHandler file to export the class itself.

Even with a wrapper that re-exports the class, Next calls new CacheHandler(ctx) with its own context (serverDistDir, revalidatedTags, maxMemoryCacheSize...). The constructor gets an options object with no dock/adapter in it and throws:

KVDockNextCacheHandler requires either 'dock' or 'adapter' option.
Enter fullscreen mode Exit fullscreen mode

createNextCacheHandler() doesn't save it, because configure() options are only used when the constructor gets no argument, and Next always passes one. What worked for me was a subclass that ignores Next's ctx:

// cache-handler.mjs
import { KVDockNextCacheHandler } from "kvdock/integrations/nextjs";
import { MemoryAdapter } from "kvdock/adapters/memory";

const adapter = new MemoryAdapter(); // or your Redis adapter
export default class CacheHandler extends KVDockNextCacheHandler {
  constructor() { super({ adapter }); }
}
Enter fullscreen mode Exit fullscreen mode

With that, set/get/revalidateTag behave. Might be worth putting in the post and README instead of the 3-line version.

The TieredDock snippet has a quieter problem. The options are l1TTL and defaultTTL, not l1Ttl / l2Ttl. TS flags it, but in plain JS they're silently ignored and nothing expires:

after 600ms (l1Ttl 200, l2Ttl 400): 1   fetcher calls: 1
same with l1TTL/defaultTTL: null
Enter fullscreen mode Exit fullscreen mode

For a lib whose pitch is fixing stale data across pods, an L1 that never expires is the exact desync you're trying to avoid. Also curious how L1 gets invalidated on pod B when pod A calls revalidateTag, is there a pub/sub, or is it just bounded by l1TTL?