feat: add Redis cache components handler for "use cache" support

examples/redis-cache-components/cache-handler.mjs

@@ -0,0 +1,27 @@
+import { createClient } from "redis";
+import { PHASE_PRODUCTION_BUILD } from "next/constants.js";
+import createRedisHandler from "@fortedigital/nextjs-cache-handler/redis-strings-cache-components";
+
+const client = createClient({
+  url: process.env.REDIS_URL || "redis://localhost:6379",
+});
+
+client.on("error", (err) => {
+  if (process.env.NEXT_PRIVATE_DEBUG_CACHE !== undefined) {
+    console.error("Redis Client Error", err);
+  }
+});
+
+// Only connect to Redis outside of `next build` — Redis is not available
+// during the build phase. The handler checks client.isReady on each method
+// call, so an unconnected client at build time is safe.
+if (process.env.NEXT_PHASE !== PHASE_PRODUCTION_BUILD) {
+  client.connect().catch((err) => {
+    console.warn("Redis connection failed:", err.message);
+  });
+}
+
+export default createRedisHandler({
+  client,
+  keyPrefix: process.env.CACHE_PREFIX || "",
+});

examples/redis-cache-components/next.config.ts

@@ -3,8 +3,8 @@ import type { NextConfig } from "next";
 const nextConfig: NextConfig = {
   cacheComponents: true,
   cacheHandlers: {
-    default: require.resolve("./cache-handler.js"),
-    remote: require.resolve("./cache-handler.js"),
+    default: require.resolve("./cache-handler.mjs"),
+    remote: require.resolve("./cache-handler.mjs"),
   },
 };
 

packages/nextjs-cache-handler/package.json

@@ -73,6 +73,9 @@
       "redis-strings": [
         "dist/handlers/redis-strings.d.ts"
       ],
+      "redis-strings-cache-components": [
+        "dist/handlers/redis-strings-cache-components.d.ts"
+      ],
       "local-lru": [
         "dist/handlers/local-lru.d.ts"
       ],

packages/nextjs-cache-handler/src/handlers/cache-components-handler.ts

@@ -1,22 +1,22 @@
 export interface CacheComponentsEntry {
-    value: ReadableStream<Uint8Array>;
-    tags: string[];
-    stale: number;
-    timestamp: number;
-    expire: number;
-    revalidate: number;
+  value: ReadableStream<Uint8Array>;
+  tags: string[];
+  stale: number;
+  timestamp: number;
+  expire: number;
+  revalidate: number;
 }
 
 export interface CacheComponentsHandler {
-    get(
-        cacheKey: string,
-        softTags: string[],
-    ): Promise<CacheComponentsEntry | undefined>;
-    set(
-        cacheKey: string,
-        pendingEntry: Promise<CacheComponentsEntry>,
-    ): Promise<void>;
-    refreshTags(): Promise<void>;
-    getExpiration(tags: string[]): Promise<number>;
-    updateTags(tags: string[], durations?: { expire?: number }): Promise<void>;
-}
+  get(
+    cacheKey: string,
+    softTags: string[],
+  ): Promise<CacheComponentsEntry | undefined>;
+  set(
+    cacheKey: string,
+    pendingEntry: Promise<CacheComponentsEntry>,
+  ): Promise<void>;
+  refreshTags(): Promise<void>;
+  getExpiration(tags: string[]): Promise<number>;
+  updateTags(tags: string[], durations?: { expire?: number }): Promise<void>;
+}

packages/nextjs-cache-handler/src/handlers/cache-handler.types.ts

@@ -50,7 +50,6 @@ export type CacheHandlerParametersGetWithTags = [
  * Context information provided during cache set operations.
  */
 export type SetContext = {
-
   /**
    * When true, the cache write should only occur if the key does not already exist.
    * Cache handlers should use non-destructive write operations (e.g., Redis NX)
@@ -154,7 +153,11 @@ export type Handler = {
    *
    * Use the absolute time (`expireAt`) to set and expiration time for the cache entry in your cache store to be in sync with the file system cache.
    */
-  set: (key: string, value: CacheHandlerValue, ctx?: SetContext) => Promise<void>;
+  set: (
+    key: string,
+    value: CacheHandlerValue,
+    ctx?: SetContext,
+  ) => Promise<void>;
   /**
    * Deletes all cache entries that are associated with the specified tag.
    * See [fetch `options.next.tags` and `revalidateTag` ↗](https://nextjs.org/docs/app/building-your-application/caching#fetch-optionsnexttags-and-revalidatetag)