If you self-host Next.js 15 on Docker, Kubernetes, Railway, Coolify, or Fly.io, you quickly run into two production caching challenges:
-
Multi-Instance Cache Desync: By default, Next.js stores ISR and App Router
fetchcaches on the local container filesystem/memory, meaning Pod A and Pod B serve inconsistent data afterrevalidateTag(). - 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
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 });
Note for
kvdock <= 0.3.2prior tobf8f1c: Next.js passes its runtimectx({ serverDistDir, maxMemoryCacheSize, ... }) tonew CacheHandler(ctx). On0.3.2, subclassingexport default class CacheHandler extends KVDockNextCacheHandler { constructor() { super({ dock }); } }ensures Next'sctxargument is handled cleanly (fixed natively increateNextCacheHandleronmainโ 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;
๐ 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:
-
TieredDockresolves the tagged keys and purges both L1 and L2. - It publishes a
{ type: "tag_invalidation", tag, keys }event over the bus. - 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!
- ๐ฎ Live Playground: https://zisam-glitch.github.io/kvdock/playground/index.html
- ๐ฆ GitHub Repo: https://github.com/zisam-glitch/kvdock
- ๐ค Author Profile: Follow @zisam-glitch 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)
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")throwsERR_PACKAGE_PATH_NOT_EXPORTED, there's no./nextin the exports map. The handler lives atkvdock/integrations/nextjs. But that module has no default export either, onlyKVDockNextCacheHandlerandcreateNextCacheHandler, 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 nodock/adapterin it and throws:createNextCacheHandler()doesn't save it, becauseconfigure()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: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
l1TTLanddefaultTTL, notl1Ttl/l2Ttl. TS flags it, but in plain JS they're silently ignored and nothing expires: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?