Horizontal Scaling with a Custom Redis cacheHandler on a Self-Hosted Next.js Setup — Is This Approach Complete?

[bogdanishere]

Horizontal Scaling with a Custom Redis cacheHandler on a Self-Hosted Next.js Setup — Is This Approach Complete?

Context

I'm planning to self-host multiple Next.js 16 instances (Docker containers behind a load balancer) and will need a shared cache layer so that:

1. All instances serve the same cached pages (no per-instance divergence).
2. revalidateTag / revalidatePath from any instance invalidates across all instances.
3. Pre-rendered pages from next build are available immediately (no cold-miss on first request).

I'm using the singular cacheHandler option in next.config.ts — the one documented for ISR and route handler responses — not cacheHandlers (plural) / use cache directives. My cache backend is Redis via the official redis package (createClient).

---

My Setup

1. next.config.ts — Registering the handler

import type { NextConfig } from "next";
import crypto from "crypto";

const nextConfig: NextConfig = {
  cacheHandler: require.resolve("./cache-handler.js"),
  cacheMaxMemorySize: 0, // Disable Next.js's built-in in-memory LRU — Redis is the single source of truth

  generateBuildId: () => process.env.GIT_HASH || crypto.randomUUID(),

  // ...security headers, images, etc.
};

export default nextConfig;

Key decisions:

• cacheMaxMemorySize: 0 — Disables Next.js's built-in in-memory LRU. Without this, each instance keeps its own stale copy, defeating shared cache. Note: my cache handler has its own small LRU (500 entries) purely as a fallback when Redis is down — this is independent from Next.js's built-in cache.
• generateBuildId from GIT_HASH — All containers share the same build, and I use this to detect new deployments in the cache handler and flush stale entries.

---

2. cache-handler.js — Full Implementation

Click to expand full cache-handler.js (~230 lines)

// cache-handler.js
// Custom Next.js Cache Handler with Redis

const { PHASE_PRODUCTION_BUILD } = require("next/constants");
const { createClient } = require("redis");
const v8 = require("v8");
const fs = require("fs");
const path = require("path");
const os = require("os");
const crypto = require("crypto");

// ─── Configuration ───────────────────────────────────────────────────
const CACHE_PREFIX = process.env.CACHE_PREFIX || "next-cache:";
const TAG_PREFIX = `${CACHE_PREFIX}tag:`;
const BUILD_ID_KEY = "__next_build_id__"; // Outside CACHE_PREFIX so SCAN doesn't delete it
const LRU_MAX_SIZE = 500;

const INSTANCE_ID =
  process.env.HOSTNAME ||
  `${os.hostname()}-${crypto.randomBytes(3).toString("hex")}`;
const DEBUG = process.env.NEXT_PRIVATE_DEBUG_CACHE === "1";

// ─── LRU Cache (fallback when Redis is down) ────────────────────────
/** @type {Map<string, {value: any, lastModified: number, tags: string[]}>} */
const lruCache = new Map();

function lruSet(key, value) {
  lruCache.delete(key);
  lruCache.set(key, value);
  if (lruCache.size > LRU_MAX_SIZE) {
    const oldest = lruCache.keys().next().value;
    lruCache.delete(oldest);
  }
}

// ─── v8 Serialization (native, fast, supports Buffer/Map/Set/Date) ──
function encode(obj) {
  return v8.serialize(obj).toString("base64");
}

function decode(str) {
  return v8.deserialize(Buffer.from(str, "base64"));
}

// ─── Redis Client (singleton, runtime only) ─────────────────────────
let client = null;
let readyResolve;
const readyPromise = new Promise((resolve) => {
  readyResolve = resolve;
});

if (PHASE_PRODUCTION_BUILD !== process.env.NEXT_PHASE) {
  try {
    client = createClient({
      url: process.env.REDIS_CACHE || "redis://localhost:6379",
      socket: {
        connectTimeout: 5000,
        reconnectStrategy(retries) {
          // Exponential backoff + jitter (prevents thundering herd in multi-instance)
          const delay = Math.min(2 ** retries * 100, 30000);
          return delay + Math.random() * 100;
        },
      },
    });

    client.on("error", (e) => {
      console.warn(`[CacheHandler] [${INSTANCE_ID}] Redis error:`, e.message);
    });

    client
      .connect()
      .then(async () => {
        // Flush cache only on new build, not on every restart
        let buildId = "unknown";
        try {
          buildId = fs
            .readFileSync(
              path.join(process.cwd(), ".next", "BUILD_ID"),
              "utf-8",
            )
            .trim();
        } catch {
          buildId = process.env.__NEXT_BUILD_ID || "unknown";
        }
        const storedBuildId = await client.get(BUILD_ID_KEY);

        if (storedBuildId !== buildId) {
          // New build detected — flush with SCAN (non-blocking)
          let cursor = "0";
          let flushed = 0;
          do {
            const [nextCursor, keys] = await client.sendCommand([
              "SCAN",
              cursor,
              "MATCH",
              `${CACHE_PREFIX}*`,
              "COUNT",
              "200",
            ]);
            cursor = nextCursor;
            if (keys.length > 0) {
              await client.del(keys);
              flushed += keys.length;
            }
          } while (cursor !== "0");
          // TAG_PREFIX (next-cache:tag:*) is already matched by CACHE_PREFIX* (next-cache:*)
          // so no need for a second SCAN loop

          await client.set(BUILD_ID_KEY, buildId);
          console.info(
            `[CacheHandler] [${INSTANCE_ID}] New build "${buildId}" — flushed ${flushed} stale entries.`,
          );
        }

        console.info(`[CacheHandler] [${INSTANCE_ID}] Redis connected.`);
        readyResolve();
      })
      .catch((e) => {
        console.warn(
          `[CacheHandler] [${INSTANCE_ID}] Redis connect failed:`,
          e.message,
        );
        // Don't set client = null — let reconnectStrategy retry.
        // client.isReady will be false, so get/set will use LRU fallback.
        readyResolve();
      });
  } catch (e) {
    console.warn("[CacheHandler] Failed to create Redis client:", e.message);
    readyResolve();
  }
} else {
  readyResolve();
}

// ─── Cache Handler Class ─────────────────────────────────────────────
module.exports = class CacheHandler {
  constructor(options) {
    this.options = options;
  }

  async get(key) {
    // Redis as source of truth
    if (client?.isReady) {
      try {
        const raw = await client.get(`${CACHE_PREFIX}${key}`);
        if (raw) {
          const entry = decode(raw);
          if (DEBUG) {
            console.log(
              `[CacheHandler] [${INSTANCE_ID}] HIT key="${key}" age=${Date.now() - entry.lastModified}ms tags=[${entry.tags?.join(",")}]`,
            );
          }
          return entry;
        }
        if (DEBUG) {
          console.log(`[CacheHandler] [${INSTANCE_ID}] MISS key="${key}"`);
        }
        return null;
      } catch (e) {
        console.warn("[CacheHandler] Redis GET error:", e.message);
      }
    }

    // Fallback to LRU only when Redis is down
    const entry = lruCache.get(key);
    if (entry) {
      // Promote-on-read: move to end (most recent) so it won't be evicted
      lruCache.delete(key);
      lruCache.set(key, entry);
      if (DEBUG) {
        console.log(`[CacheHandler] [${INSTANCE_ID}] LRU-HIT key="${key}"`);
      }
      return entry;
    }

    return null;
  }

  async set(key, data, ctx) {
    const tags = ctx?.tags ? [...ctx.tags] : [];

    // Also extract tags from headers (Next.js may send them here)
    if (data?.headers?.["x-next-cache-tags"]) {
      const headerTags = data.headers["x-next-cache-tags"].split(",");
      tags.push(...headerTags);
    }

    const uniqueTags = [...new Set(tags)];

    const entry = {
      value: data,
      lastModified: Date.now(),
      tags: uniqueTags,
    };

    // Save to LRU (bounded)
    lruSet(key, entry);

    if (client?.isReady) {
      try {
        const serialized = encode(entry);
        const redisKey = `${CACHE_PREFIX}${key}`;

        // TTL with 60s buffer for stale-while-revalidate
        // ctx.cacheControl.revalidate (APP_PAGE/APP_ROUTE) or data.revalidate (FETCH/IMAGE)
        const revalidate = ctx?.cacheControl?.revalidate ?? data?.revalidate;
        // Multiplicative buffer: max(2x, +60s) — works well
        // for both short (10s→80s) and long (3600s→7200s) revalidate values
        const ttl =
          typeof revalidate === "number" && revalidate > 0
            ? Math.max(revalidate * 2, revalidate + 60)
            : 0;

        if (ttl > 0) {
          await client.set(redisKey, serialized, { EX: ttl });
        } else {
          await client.set(redisKey, serialized);
        }

        if (DEBUG) {
          console.log(
            `[CacheHandler] [${INSTANCE_ID}] SET key="${key}" tags=[${uniqueTags.join(",")}] revalidate=${revalidate || "none"}`,
          );
        }

        // Tag → keys index (no EXPIRE — tag sets are cleaned up by revalidateTag())
        // EXPIRE could shorten the existing TTL of a tag set shared between entries with different revalidate values
        if (uniqueTags.length > 0) {
          const pipeline = client.multi();
          for (const tag of uniqueTags) {
            pipeline.sAdd(`${TAG_PREFIX}${tag}`, redisKey);
          }
          await pipeline.execAsPipeline();
        }
      } catch (e) {
        console.warn("[CacheHandler] Redis SET error:", e.message);
      }
    }
  }

  async revalidateTag(tags) {
    tags = [tags].flat();

    if (DEBUG) {
      console.log(
        `[CacheHandler] [${INSTANCE_ID}] REVALIDATE tags=[${tags.join(",")}]`,
      );
    }

    // Clear from LRU
    for (const [key, value] of lruCache) {
      if (value.tags?.some((tag) => tags.includes(tag))) {
        lruCache.delete(key);
      }
    }

    // Clear from Redis via tag index
    if (client?.isReady) {
      try {
        const keysToDelete = new Set();

        for (const tag of tags) {
          const tagKey = `${TAG_PREFIX}${tag}`;
          const members = await client.sMembers(tagKey);
          for (const member of members) {
            keysToDelete.add(member);
          }
          await client.del(tagKey);
        }

        if (keysToDelete.size > 0) {
          await client.del([...keysToDelete]);
        }
      } catch (e) {
        console.warn("[CacheHandler] Redis REVALIDATE error:", e.message);
      }
    }
  }

  resetRequestCache() {}

  // Debug helpers
  static getInstanceId() {
    return INSTANCE_ID;
  }

  static getRedisClient() {
    return client;
  }

  static getLruSize() {
    return lruCache.size;
  }

  // Promise that resolves after connect + flush (if needed)
  static ready() {
    return readyPromise;
  }
};

Design notes:

• v8.serialize — Handles Buffer (for .rsc data), Map (for segmentData), and other non-JSON types natively, which JSON.stringify cannot.
• LRU fallback — Only read from when client.isReady === false. This is separate from Next.js's built-in in-memory cache (disabled via cacheMaxMemorySize: 0). It's purely a resilience layer so the app doesn't crash if Redis goes down.
• SCAN instead of KEYS for flush — Non-blocking in production Redis.
• Tag → keys index via Redis Sets — revalidateTag looks up all keys for a tag and deletes them atomically.
• TTL with buffer — max(revalidate * 2, revalidate + 60) gives stale-while-revalidate room to work.
• Build ID tracking — On connect, compares current BUILD_ID with stored value. If different, flushes all CACHE_PREFIX* keys via SCAN.

---

3. instrumentation.ts + instrumentation.node.ts — Pre-populating Redis from Build Output

This is the piece I'm most uncertain about.

The problem: next build writes pre-rendered pages directly to .next/server/app/ on disk and never calls set() on the cache handler. At runtime, Next.js calls get() through the cache handler. Result: every pre-rendered page is a cache miss on first request → unnecessary re-render.

My solution: At server startup (via the register() function in instrumentation.ts), I read the build output and manually populate Redis:

// instrumentation.ts
export async function register() {
  const { populateCache } = await import("./instrumentation.node");
  await populateCache();
}

// instrumentation.node.ts (simplified)
import fs from "fs/promises";
import path from "path";

export async function populateCache() {
  try {
    const CacheHandler = require("./cache-handler.js");
    await CacheHandler.ready(); // Wait for Redis connect + flush

    const handler = new CacheHandler({});
    const serverDir = path.join(process.cwd(), ".next", "server", "app");

    try {
      await fs.access(serverDir);
    } catch {
      console.log("[instrumentation] No .next/server/app directory, skipping");
      return;
    }

    await populateFromBuildOutput(handler, serverDir, "");
    console.log("[instrumentation] Cache pre-populated from build output");
  } catch (err) {
    console.error("[instrumentation] Failed to pre-populate cache:", err);
  }
}

async function populateFromBuildOutput(handler, baseDir, routePrefix) {
  const entries = await fs.readdir(baseDir, { withFileTypes: true });

  for (const entry of entries) {
    const fullPath = path.join(baseDir, entry.name);

    if (entry.isDirectory()) {
      await populateFromBuildOutput(
        handler,
        fullPath,
        `${routePrefix}/${entry.name}`,
      );
      continue;
    }

    if (entry.name.endsWith(".html")) {
      const baseName = entry.name.replace(/\.html$/, "");
      const rscPath = path.join(baseDir, `${baseName}.rsc`);
      const metaPath = path.join(baseDir, `${baseName}.meta`);

      const routeKey =
        baseName === "index"
          ? routePrefix || "/"
          : `${routePrefix}/${baseName}`;

      try {
        const html = await fs.readFile(fullPath, "utf-8");

        let rscData;
        try {
          rscData = await fs.readFile(rscPath);
        } catch {}

        let meta = {};
        try {
          meta = JSON.parse(await fs.readFile(metaPath, "utf-8"));
        } catch {}

        const tags = meta?.headers?.["x-next-cache-tags"]
          ? meta.headers["x-next-cache-tags"].split(",")
          : [routeKey];

        // Read segmentData from .segments/ (per-segment prefetch for PPR)
        let segmentData;
        if (meta.segmentPaths?.length) {
          const segmentsDir = path.join(baseDir, `${baseName}.segments`);
          segmentData = new Map();
          for (const segmentPath of meta.segmentPaths) {
            const segFilePath = path.join(
              segmentsDir,
              segmentPath + ".segment.rsc",
            );
            try {
              segmentData.set(segmentPath, await fs.readFile(segFilePath));
            } catch {}
          }
          if (segmentData.size === 0) segmentData = undefined;
        }

        await handler.set(
          routeKey,
          {
            kind: "APP_PAGE",
            html,
            rscData,
            headers: meta.headers,
            status: meta.status ?? 200,
            postponed: meta.postponed ?? undefined,
            segmentData,
          },
          { tags },
        );
      } catch (err) {
        console.warn(`[instrumentation] Skipping ${routeKey}:`, err);
      }
    }
  }
}

---

My Open Questions

1. Is the build-output pre-population approach correct?

I'm reconstructing the IncrementalCacheEntry shape manually from the .html, .rsc, .meta, and .segments/ files. This works today on Next.js 16, but:

• Is this shape stable? Or is it an internal implementation detail that could change between minor versions?
• Am I missing any fields? I handle kind, html, rscData, headers, status, postponed, and segmentData. Are there others?
• Is there a planned API to let the cache handler receive build output natively, so we don't have to reverse-engineer the file structure?

2. What about FETCH cache entries?

My instrumentation only handles APP_PAGE entries. But next build also generates fetch cache entries in .next/cache/fetch-cache/.

• Should I also pre-populate fetch cache entries into Redis?
• Or does the runtime re-fetch them gracefully on miss?

3. Race condition during rolling deployments

When deploying N containers:

• Container 1 starts → detects new BUILD_ID → flushes Redis → populates from build output.
• Container 2 starts seconds later → sees the same BUILD_ID already in Redis → skips flush.

But what if Container 2 starts while Container 1 is still populating? Could it serve requests with a partially-populated cache? I handle this with a ready() promise + Redis lock, but is there a better pattern?

Related: the self-hosting docs mention deploymentId for version skew protection. Does deploymentId interact with cacheHandler in any way? Or is it purely for client-side asset/navigation consistency?

4. revalidateTag propagation across instances

My revalidateTag deletes keys from Redis, which works because all instances read from the same Redis. But:

• When Instance A revalidates, Instance B just gets a cache miss on next get() and re-renders. Is that the expected behavior?
• Since cacheMaxMemorySize: 0 disables Next.js's built-in LRU, are there any other in-process caches that could serve stale data?

5. Tag sets growing indefinitely in Redis

My tag index (tag:* → Set of cache keys) doesn't have an EXPIRE. Cache entries themselves expire via TTL, but the tag sets accumulate stale pointers over time. revalidateTag cleans them up, but tags that are never explicitly revalidated grow indefinitely.

Is adding an EXPIRE on tag sets safe? Or would that risk losing the index before a revalidation happens? What's the recommended cleanup strategy?

6. Dynamic routes and generateStaticParams

For routes like /blog/[slug] with generateStaticParams:

• Are build outputs always stored as actual-param-value.html (e.g., my-post.html)?
• Do catch-all routes ([...slug]) need special handling?

7. Streaming interaction with cache handler

The self-hosting docs mention disabling proxy buffering for streaming. Does streaming interact with the cache handler? Are streamed responses cached differently, or does the handler only see the final complete response?

---

What I'm Hoping For

• Confirmation whether the singular cacheHandler + instrumentation pre-population is a viable pattern for horizontal scaling.
• Guidance on which parts depend on internal implementation details vs. stable contracts.
• Any known gotchas or missing pieces.

I understand cacheHandlers (plural) with use cache is the newer direction, but I'm on a production app using the singular cacheHandler and want to make sure this approach is solid before considering migration.

---

Environment

Binaries:
  Node: 22.22.0
  npm: 11.5.2
  Yarn: 1.22.22
  pnpm: 10.28.1
Relevant Packages:
  next: 16.1.7
  eslint-config-next: N/A
  react: 19.2.3
  react-dom: 19.2.3
  typescript: 5.9.3

• Self-hosted (Docker containers behind a load balancer via Docker Swarm, built with Railpack)
• No output: "standalone"
• Redis 7 (via redis / createClient)
• Using instrumentation.ts for cache warm-up at server startup

Thanks for any feedback!

[Nickalus12]

It looks like you've done the heavy lifting here. Disabling cacheMaxMemorySize is the right move because, as you noted, the default in-memory cache is the biggest hurdle for horizontal scaling—it creates those "ghost" updates where one instance is fresh and the other is stale.

Your approach is mostly complete, but there are two "gotchas" that might trip you up in a production environment:

1. Tag Invalidation Performance
If your revalidateTag implementation relies on SCAN to find keys associated with a tag, it's going to get slow as your Redis DB grows. A more robust way to handle this is to store a mapping of tag -> [keys] in a Redis Set. When a tag is invalidated, you fetch the set, delete the keys, and then delete the set.

2. Image Optimization
By default, Next.js caches optimized images on the local file system (.next/cache/images). In a scaled environment, if Instance A optimizes an image, Instance B won't have it. You should add this to your next.config.ts to ensure your Redis handler also manages image cache:

const nextConfig: NextConfig = {
  cacheHandler: require.resolve("./cache-handler.js"),
  images: {
    customCacheHandler: true,
  },
  // ...
};

3. The "First Request" Cold Miss
Since you're using next build, your pre-rendered HTML/JSON is generated at build time and sits on the disk of the container that ran the build. When you deploy, you need to ensure these files are actually pushed to Redis during the build process (using the PHASE_PRODUCTION_BUILD constant in your handler) or that you have a shared volume for .next/cache/fetch-cache. If you only rely on the get call to populate Redis, the very first request to a specific instance for a pre-rendered page might still hit the local disk before it ever populates your shared Redis.

Otherwise, using generateBuildId to namespace your cache is exactly how you prevent version mismatch during rolling deploys. Looks solid.