Feature Request: Add support for non-destructive Redis hydration via `NX` option in `registerInitialCache` (for v2.0.0)

[zto-sbenning]

Is your feature request related to a problem? Please describe.

Yes — currently, the Redis hydration behavior during registerInitialCache() is destructive by default. When the application starts, it writes all static/build-time cache entries into Redis, overwriting any existing keys.

This causes two significant problems:

1. On app restart: if any cache entries have been updated at runtime (e.g., via revalidateTag() or ISR revalidations), restarting the app will overwrite the fresher data with outdated build-time values.
2. On horizontal scaling: if a new instance of the app starts later (for scaling), it can invalidate runtime-generated cache data by writing build-time defaults.

This results in stale content being served even though Redis held fresher versions.

Describe the solution you'd like

We should be able to configure the instrumentation (registerInitialCache) to perform non-destructive hydration — meaning:

• Use the NX option of the Redis SET command,
• So Redis keys are only written if they don’t already exist.

This could be introduced via a config flag in the instrumentation options:

registerInitialCache({
  redisClient,
  cacheEntries,
  skipIfExists: true // or: redisNX: true, or other ..
});

Internally, this would translate into Redis SET calls like:

client.set(..., { NX: true });

Additional context

This kind of feature is especially important in ISR production setups where:

• Cache freshness is critical,
• Redeployments or horizontal scaling are common,
• Runtime revalidations must take precedence over build-time defaults.

Possible oversight?

It's possible that this behavior is already implemented or configurable and I may have missed it.

However, based on my testing, the current behavior results in runtime cache being overwritten by build-time values during both application restarts and horizontal scaling scenarios, as described above.

Version compatibility

From what I understand, this feature may not be feasible to implement before version v2.0.0.

Currently, registerInitialCache() relies on the legacy package @neshca/cache-handler, which sits between it and the underlying Redis client. Even if a config flag was added at the registerInitialCache level, the legacy package would not propagate it to the Redis SET operation — making the NX behavior unimplementable in practice.

However, since v2.0.0 removes this dependency and gives full control back to @fortedigital/nextjs-cache-handler, I believe this feature could be cleanly introduced as part of that version or shortly after.

---

Let me know if you'd like help with a PR — I'd be happy to contribute!
I'd also really appreciate your thoughts on this — curious to hear your perspective.

[AyronK]

Thanks for the issue and I think you're right that it's not implemented in the original neshca package. Although in 1.3.0 we have already moved the instrumentation code to our package. I will take a look and perhaps we can implement it before 2.0.0.

FYI

if (process.env.NEXT_RUNTIME === "nodejs") {
    const { registerInitialCache } = await import("@fortedigital/nextjs-cache-handler/instrumentation");
    const CacheHandler = (await import("./cache-handler.js")).default;
    await registerInitialCache(CacheHandler);
}

EDIT: I checked that this option would need to be propagated to the CacheHandler implementation, so it's impossible to do before 2.0.0

EDIT2: It means we need to propagate and implement the option on all handlers. It's a bit time consuming, I don't think we'll make it in 2.0.0, but perhaps 2.1.0 soon after.

[zto-sbenning]

Hi,

Thank you for planning it! As I said, I'd be happy to help.

---

In the meantime, a potential workaround could be to control the instrumentation based on an environment variable. Something like:

export async function register() {
  if (
    process.env.NEXT_RUNTIME === 'nodejs' &&
    process.env.SKIP_REGISTER_INITIAL_CACHE === undefined
  ) {
    const { registerInitialCache } = await import('@fortedigital/nextjs-cache-handler/instrumentation');
    const CacheHandler = (await import('../cache-handler.mjs')).default;
    await registerInitialCache(CacheHandler, {
      pages: true,
      fetch: true,
      routes: true,
    });
  }
}

If one can control the .env file during scaling or restarts, this should do the trick — not ideal, though!

[itpartners-tomasz]

Another idea for a temporary workaround:

During application startup, I check if a key already exists in Redis. If it does, I simply skip the hydration step.
I use 'nextjs:' + buildId + ':' as the key prefix.
It’s not elegant, but it works.

I’m also happy to contribute to this feature if needed.

import { PHASE_PRODUCTION_BUILD } from "next/constants.js";

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {

    if (PHASE_PRODUCTION_BUILD !== process.env.NEXT_PHASE && process.env.NODE_ENV === "production" && 
  !!process.env.REDIS_URL) {
      const destDir='build';
      const { readFileSync } = await import('fs');
      const { join } = (await import('path')).default;
      const buildIdPath = join(process.cwd(), destDir, 'BUILD_ID');
      const buildId = readFileSync(buildIdPath, 'utf8').trim();
      const { setupRedisClient } = await import('../cache-handler.mjs');
      const client = await setupRedisClient();
      const exists = await client?.exists('nextjs:' + buildId + ':__sharedTags__');
      if (exists) {
        console.info("Redis cache detected for build ID:", buildId);
      } else {
        const { registerInitialCache } = await import('@fortedigital/nextjs-cache-handler/instrumentation');
        const CacheHandler = (await import("../cache-handler.mjs")).default;
        console.info("Registering initial cache handler for Next.js instrumentation.");
        await registerInitialCache(CacheHandler,{buildDir: destDir});
      }
    }
  }
}

[AyronK]

All right, I'm looking back at some older issues and this one seems nice to have. The workaround sounds fine but I don't think it gives as much control as you either skip instrumentation completely or not. Having an option for skipping existing keys on instrumentation seems like a good idea. I'll explore what's the best option to integrate it, however I don't think it would be registerInitialCache setting as it's abstraction level doesn't fit redis-specific features. I am thinking either a config on redis handler or a env variable.