@trieb.work/nextjs-turbo-redis-cache 1.10.3 → 1.11.0

package/.github/workflows/ci.yml

@@ -25,12 +25,15 @@ jobs:
       pull-requests: write # Grant write access to pull request comments
     strategy:
       matrix:
-        next-test-app:
-          - next-app-15-0-3
-          - next-app-15-3-2
-          - next-app-15-4-7
-          - next-app-16-0-3
-          - next-app-16-1-1
+        include:
+          - next-test-app: next-app-15-0-3
+            run-cache-components: false
+          - next-test-app: next-app-15-3-2
+            run-cache-components: false
+          - next-test-app: next-app-15-4-7
+            run-cache-components: false
+          - next-test-app: next-app-16-0-3
+            run-cache-components: true
 
     steps:
       - name: Checkout code
@@ -78,18 +81,29 @@ jobs:
           SKIP_BUILD: true
           NEXT_TEST_APP: ${{ matrix.next-test-app }}
 
-      - name: Install Playwright browsers (Next 16 only)
-        if: startsWith(matrix.next-test-app, 'next-app-16')
+      - name: Install Cache Components Integration Test Project
+        if: matrix.run-cache-components
+        run: cd test/integration/next-app-16-1-1-cache-components && pnpm install
+
+      - name: Build Cache Components Integration Test Project
+        if: matrix.run-cache-components
+        run: cd test/integration/next-app-16-1-1-cache-components && pnpm build
+
+      - name: Run Cache Components integration tests
+        if: matrix.run-cache-components
+        run: pnpm test:cache-components
+
+      - name: Install Playwright browsers
+        if: matrix.run-cache-components
         run: pnpm exec playwright install --with-deps
 
-      - name: Run Playwright E2E tests (Next 16 only)
-        if: startsWith(matrix.next-test-app, 'next-app-16')
+      - name: Run Playwright E2E tests
+        if: matrix.run-cache-components
         run: pnpm test:e2e
         env:
-          PLAYWRIGHT_BASE_URL: http://localhost:3055
+          PLAYWRIGHT_BASE_URL: http://localhost:3101
 
       - name: Code Coverage Comments
-      # only run for pull requests from this repository - so no problems for external PRs
         if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
         uses: kcjpop/coverage-comments@v2.2
         with:

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [1.11.0](https://github.com/trieb-work/nextjs-turbo-redis-cache/compare/v1.10.3...v1.11.0) (2026-02-16)
+
+
+### Features
+
+* release cache components ([#67](https://github.com/trieb-work/nextjs-turbo-redis-cache/issues/67)) ([815e66b](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/815e66bab21f58d77693cad2a9d73f95ff8e7d79))
+
 ## [1.10.3](https://github.com/trieb-work/nextjs-turbo-redis-cache/compare/v1.10.2...v1.10.3) (2026-01-12)
 
 

package/README.md

@@ -1,7 +1,7 @@
 # nextjs-turbo-redis-cache
 
 [![npm version](https://img.shields.io/npm/v/@trieb.work/nextjs-turbo-redis-cache.svg)](https://www.npmjs.com/package/@trieb.work/nextjs-turbo-redis-cache)
-![Turbo redis cache image](https://github.com/user-attachments/assets/98e0dfd9-f38a-42ad-a355-9843740cc2d6)
+![Turbo redis cache image](https://github.com/user-attachments/assets/4103191e-4f4d-4139-a519-0b5bfab3e8b4)
 
 The ultimate Redis caching solution for Next.js 15 and the app router. Built for production-ready, large-scale projects, it delivers unparalleled performance and efficiency with features tailored for high-traffic applications. This package has been created after extensibly testing the @neshca package and finding several major issues with it.
 
@@ -28,8 +28,11 @@ Tested versions are:
 - Nextjs 15.4.7 + redis client 4.7.0
 - Nextjs 16.0.3 + redis client 4.7.0 (cacheComponents: false)
 - Nextjs 16.1.1 + redis client 4.7.0 (cacheComponents: false)
+- Nextjs 16.1.1 + redis client 4.7.0 (cacheComponents: true)
 
-Currently PPR, 'use cache', cacheLife and cacheTag are not tested. Use these operations with caution and your own risk. [Cache Components](https://nextjs.org/docs/app/getting-started/cache-components) support is in development.
+Currently PPR, 'use cache', cacheLife and cacheTag are not tested. Use these operations with caution and your own risk. [Cache Components](https://nextjs.org/docs/app/getting-started/cache-components) are supported experimentally (Next.js 16+).
+
+For Cache Components, see the "Cache Components handler (Next.js 16+)" section below.
 
 ## Getting started
 
@@ -215,6 +218,12 @@ To run all tests you can use the following command:
 pnpm build && pnpm test
 ```
 
+Folder layout / runners:
+
+- **Vitest** (unit + integration) lives in `src/**/*.test.ts(x)` and `test/**`.
+- **Playwright** (E2E) lives in `tests/**` (see `playwright.config.ts`).
+- `test/browser/**` contains Vitest tests that hit a running Next.js app over HTTP. Despite the folder name, this is not Playwright and does not use Vitest browser mode.
+
 ### Unit tests
 
 To run unit tests you can use the following command:
@@ -231,6 +240,14 @@ To run integration tests you can use the following command:
 pnpm build && pnpm test:integration
 ```
 
+### E2E tests (Playwright)
+
+To run Playwright tests (`tests/**`) you can use:
+
+```bash
+pnpm test:e2e
+```
+
 The integration tests will start a Next.js server and test the caching handler. You can modify testing behavior by setting the following environment variables:
 
 - SKIP_BUILD: If set to true, the integration tests will not build the Next.js app. Therefore the nextjs app needs to be built before running the tests. Or you execute the test once without skip build and the re-execute `pnpm test:integration` with skip build set to true.
@@ -239,6 +256,88 @@ The integration tests will start a Next.js server and test the caching handler.
 
 Integration tests may have dependencies between test cases, so individual test failures should be evaluated in the context of the full test suite rather than in isolation.
 
+## Cache Components handler (Next.js 16+)
+
+This package can be used as a Cache Components handler (Node.js runtime) for Next.js apps that enable Cache Components.
+
+This is experimental support and the Next.js Cache Components APIs may still change. We don't have a larger production project right now available to test this in real world conditions.
+
+### Enable Cache Components + cache handler
+
+Install the package in your Next.js app:
+
+```bash
+pnpm add @trieb.work/nextjs-turbo-redis-cache redis
+```
+
+In your Next.js app, enable Cache Components and point `cacheHandlers.default` to a module that exports the handler instance:
+
+```ts
+// next.config.ts
+import type { NextConfig } from 'next';
+
+const nextConfig: NextConfig = {
+  cacheComponents: true,
+  cacheHandlers: {
+    default: require.resolve('./cache-handler.js'),
+  },
+};
+
+export default nextConfig;
+```
+
+```js
+// cache-handler.js
+const { redisCacheHandler } = require('@trieb.work/nextjs-turbo-redis-cache');
+
+module.exports = redisCacheHandler;
+```
+
+If you prefer ESM:
+
+```js
+// cache-handler.js
+import { redisCacheHandler } from '@trieb.work/nextjs-turbo-redis-cache';
+
+export default redisCacheHandler;
+```
+
+### Required environment variables
+
+- `REDIS_URL` (recommended): e.g. `redis://localhost:6379`
+
+Optional:
+
+- `VERCEL_URL`: used as a key prefix for multi-tenant isolation (also useful in tests). If unset, a default prefix is used.
+- `REDIS_COMMAND_TIMEOUT_MS`: timeout (ms) for Redis commands used by the handler.
+
+### Local manual testing (Cache Lab)
+
+This repo includes a dedicated Next.js Cache Components integration app with real pages for manual testing.
+
+1. Start Redis locally.
+1. Install + start the Cache Components test app:
+
+```bash
+pnpm -C test/integration/next-app-16-1-1-cache-components install
+pnpm -C test/integration/next-app-16-1-1-cache-components dev
+```
+
+Then open the Cache Lab pages:
+
+- `/cache-lab`
+- `/cache-lab/use-cache-nondeterministic`
+- `/cache-lab/cachelife-short`
+- `/cache-lab/tag-invalidation`
+- `/cache-lab/stale-while-revalidate`
+- `/cache-lab/runtime-data-suspense`
+
+To run the Playwright E2E tests against a running dev server:
+
+```bash
+PLAYWRIGHT_BASE_URL=http://localhost:3101 pnpm test:e2e
+```
+
 ## Some words on nextjs caching internals
 
 Nextjs will use different caching objects for different pages and api routes. Currently supported are kind: APP_ROUTE and APP_PAGE.

package/dist/index.d.mts

@@ -149,4 +149,25 @@ declare class CachedHandler {
     resetRequestCache(...args: Parameters<RedisStringsHandler['resetRequestCache']>): ReturnType<RedisStringsHandler['resetRequestCache']>;
 }
 
-export { type CreateRedisStringsHandlerOptions, RedisStringsHandler, CachedHandler as default };
+interface CacheComponentsEntry {
+    value: ReadableStream<Uint8Array>;
+    tags: string[];
+    stale: number;
+    timestamp: number;
+    expire: number;
+    revalidate: number;
+}
+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>;
+}
+type CreateCacheComponentsHandlerOptions = CreateRedisStringsHandlerOptions;
+declare function getRedisCacheComponentsHandler(options?: CreateCacheComponentsHandlerOptions): CacheComponentsHandler;
+declare const redisCacheHandler: CacheComponentsHandler;
+
+export { type CreateRedisStringsHandlerOptions, RedisStringsHandler, CachedHandler as default, getRedisCacheComponentsHandler, redisCacheHandler };

package/dist/index.d.ts

@@ -149,4 +149,25 @@ declare class CachedHandler {
     resetRequestCache(...args: Parameters<RedisStringsHandler['resetRequestCache']>): ReturnType<RedisStringsHandler['resetRequestCache']>;
 }
 
-export { type CreateRedisStringsHandlerOptions, RedisStringsHandler, CachedHandler as default };
+interface CacheComponentsEntry {
+    value: ReadableStream<Uint8Array>;
+    tags: string[];
+    stale: number;
+    timestamp: number;
+    expire: number;
+    revalidate: number;
+}
+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>;
+}
+type CreateCacheComponentsHandlerOptions = CreateRedisStringsHandlerOptions;
+declare function getRedisCacheComponentsHandler(options?: CreateCacheComponentsHandlerOptions): CacheComponentsHandler;
+declare const redisCacheHandler: CacheComponentsHandler;
+
+export { type CreateRedisStringsHandlerOptions, RedisStringsHandler, CachedHandler as default, getRedisCacheComponentsHandler, redisCacheHandler };

package/dist/index.js

@@ -21,7 +21,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   RedisStringsHandler: () => RedisStringsHandler,
-  default: () => index_default
+  default: () => index_default,
+  getRedisCacheComponentsHandler: () => getRedisCacheComponentsHandler,
+  redisCacheHandler: () => redisCacheHandler
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -975,10 +977,324 @@ var CachedHandler = class {
   }
 };
 
+// src/CacheComponentsHandler.ts
+var import_redis2 = require("redis");
+var REVALIDATED_TAGS_KEY2 = "__cacheComponents_revalidated_tags__";
+var SHARED_TAGS_KEY = "__cacheComponents_sharedTags__";
+var killContainerOnErrorCount2 = 0;
+async function streamToBuffer(stream) {
+  const reader = stream.getReader();
+  const chunks = [];
+  while (true) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    if (value) {
+      chunks.push(value);
+    }
+  }
+  if (chunks.length === 1) {
+    return chunks[0];
+  }
+  const totalLength = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0);
+  const result = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const chunk of chunks) {
+    result.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return result;
+}
+function bufferToReadableStream(buffer) {
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue(buffer);
+      controller.close();
+    }
+  });
+}
+var RedisCacheComponentsHandler = class {
+  constructor({
+    redisUrl = process.env.REDIS_URL ? process.env.REDIS_URL : process.env.REDISHOST ? `redis://${process.env.REDISHOST}:${process.env.REDISPORT}` : "redis://localhost:6379",
+    database = process.env.VERCEL_ENV === "production" ? 0 : 1,
+    keyPrefix = process.env.VERCEL_URL || "UNDEFINED_URL_",
+    getTimeoutMs = process.env.REDIS_COMMAND_TIMEOUT_MS ? Number.parseInt(process.env.REDIS_COMMAND_TIMEOUT_MS) ?? 500 : 500,
+    revalidateTagQuerySize = 250,
+    avgResyncIntervalMs = 60 * 60 * 1e3,
+    socketOptions,
+    clientOptions,
+    killContainerOnErrorThreshold = process.env.KILL_CONTAINER_ON_ERROR_THRESHOLD ? Number.parseInt(process.env.KILL_CONTAINER_ON_ERROR_THRESHOLD) ?? 0 : 0
+  }) {
+    try {
+      this.keyPrefix = keyPrefix;
+      this.getTimeoutMs = getTimeoutMs;
+      this.client = (0, import_redis2.createClient)({
+        url: redisUrl,
+        pingInterval: 1e4,
+        ...database !== 0 ? { database } : {},
+        ...socketOptions ? { socket: { ...socketOptions } } : {},
+        ...clientOptions || {}
+      });
+      this.client.on("error", (error) => {
+        console.error(
+          "RedisCacheComponentsHandler client error",
+          error,
+          killContainerOnErrorCount2++
+        );
+        setTimeout(
+          () => this.client.connect().catch((err) => {
+            console.error(
+              "Failed to reconnect RedisCacheComponentsHandler client after connection loss:",
+              err
+            );
+          }),
+          1e3
+        );
+        if (killContainerOnErrorThreshold > 0 && killContainerOnErrorCount2 >= killContainerOnErrorThreshold) {
+          console.error(
+            "RedisCacheComponentsHandler client error threshold reached, disconnecting and exiting (please implement a restart process/container watchdog to handle this error)",
+            error,
+            killContainerOnErrorCount2++
+          );
+          this.client.disconnect();
+          this.client.quit();
+          setTimeout(() => {
+            process.exit(1);
+          }, 500);
+        }
+      });
+      this.client.connect().then(() => {
+        debug("green", "RedisCacheComponentsHandler client connected.");
+      }).catch(() => {
+        this.client.connect().catch((error) => {
+          console.error(
+            "Failed to connect RedisCacheComponentsHandler client:",
+            error
+          );
+          this.client.disconnect();
+          throw error;
+        });
+      });
+      const filterKeys = (key) => key !== REVALIDATED_TAGS_KEY2 && key !== SHARED_TAGS_KEY;
+      this.revalidatedTagsMap = new SyncedMap({
+        client: this.client,
+        keyPrefix,
+        redisKey: REVALIDATED_TAGS_KEY2,
+        database,
+        querySize: revalidateTagQuerySize,
+        filterKeys,
+        resyncIntervalMs: avgResyncIntervalMs + avgResyncIntervalMs / 10 + Math.random() * (avgResyncIntervalMs / 10)
+      });
+      this.sharedTagsMap = new SyncedMap({
+        client: this.client,
+        keyPrefix,
+        redisKey: SHARED_TAGS_KEY,
+        database,
+        querySize: revalidateTagQuerySize,
+        filterKeys,
+        resyncIntervalMs: avgResyncIntervalMs - avgResyncIntervalMs / 10 + Math.random() * (avgResyncIntervalMs / 10)
+      });
+    } catch (error) {
+      console.error("RedisCacheComponentsHandler constructor error", error);
+      throw error;
+    }
+  }
+  async assertClientIsReady() {
+    if (!this.client.isReady && !this.client.isOpen) {
+      await this.client.connect().catch((error) => {
+        console.error(
+          "RedisCacheComponentsHandler assertClientIsReady reconnect error:",
+          error
+        );
+        throw error;
+      });
+    }
+    await Promise.all([
+      this.revalidatedTagsMap.waitUntilReady(),
+      this.sharedTagsMap.waitUntilReady()
+    ]);
+  }
+  async computeMaxRevalidation(tags) {
+    let max = 0;
+    for (const tag of tags) {
+      const ts = this.revalidatedTagsMap.get(tag);
+      if (ts && ts > max) {
+        max = ts;
+      }
+    }
+    return max;
+  }
+  async get(cacheKey, softTags) {
+    const redisKey = `${this.keyPrefix}${cacheKey}`;
+    try {
+      await this.assertClientIsReady();
+      const serialized = await redisErrorHandler(
+        "RedisCacheComponentsHandler.get(), operation: get " + this.getTimeoutMs + "ms " + redisKey,
+        this.client.get(
+          (0, import_redis2.commandOptions)({ signal: AbortSignal.timeout(this.getTimeoutMs) }),
+          redisKey
+        )
+      );
+      if (!serialized) {
+        return void 0;
+      }
+      const stored = JSON.parse(serialized);
+      const now = Date.now();
+      const expiryTime = stored.timestamp + stored.expire * 1e3;
+      if (Number.isFinite(stored.expire) && stored.expire > 0 && now > expiryTime) {
+        await this.client.unlink(redisKey).catch(() => {
+        });
+        await this.sharedTagsMap.delete(cacheKey).catch(() => {
+        });
+        return void 0;
+      }
+      const maxRevalidation = await this.computeMaxRevalidation([
+        ...stored.tags || [],
+        ...softTags || []
+      ]);
+      if (maxRevalidation > 0 && maxRevalidation > stored.timestamp) {
+        await this.client.unlink(redisKey).catch(() => {
+        });
+        await this.sharedTagsMap.delete(cacheKey).catch(() => {
+        });
+        return void 0;
+      }
+      const valueBuffer = typeof stored.value === "string" ? new Uint8Array(Buffer.from(stored.value, "base64")) : stored.value;
+      return {
+        ...stored,
+        value: bufferToReadableStream(valueBuffer)
+      };
+    } catch (error) {
+      console.error(
+        "RedisCacheComponentsHandler.get() Error occurred while getting cache entry. Returning undefined so site can continue to serve content while cache is disabled. The original error was:",
+        error,
+        killContainerOnErrorCount2++
+      );
+      return void 0;
+    }
+  }
+  async set(cacheKey, pendingEntry) {
+    try {
+      await this.assertClientIsReady();
+      const entry = await pendingEntry;
+      const [storeStream] = entry.value.tee();
+      const buffer = await streamToBuffer(storeStream);
+      const stored = {
+        value: Buffer.from(buffer).toString("base64"),
+        tags: entry.tags || [],
+        stale: entry.stale,
+        timestamp: entry.timestamp,
+        expire: entry.expire,
+        revalidate: entry.revalidate
+      };
+      let serialized;
+      try {
+        const cleanStored = {
+          value: stored.value,
+          tags: Array.isArray(stored.tags) ? [...stored.tags] : [],
+          stale: Number(stored.stale),
+          timestamp: Number(stored.timestamp),
+          expire: Number(stored.expire),
+          revalidate: Number(stored.revalidate)
+        };
+        serialized = JSON.stringify(cleanStored);
+      } catch (jsonError) {
+        console.error("JSON.stringify error:", jsonError);
+        console.error("Stored object:", stored);
+        throw jsonError;
+      }
+      const ttlSeconds = Number.isFinite(stored.expire) && stored.expire > 0 ? Math.floor(stored.expire) : void 0;
+      const redisKey = `${this.keyPrefix}${cacheKey}`;
+      const setOperation = redisErrorHandler(
+        "RedisCacheComponentsHandler.set(), operation: set " + redisKey,
+        this.client.set(redisKey, serialized, {
+          ...ttlSeconds ? { EX: ttlSeconds } : {}
+        })
+      );
+      let tagsOperation;
+      const tags = stored.tags || [];
+      if (tags.length > 0) {
+        const currentTags = this.sharedTagsMap.get(cacheKey);
+        const currentIsSameAsNew = currentTags?.length === tags.length && currentTags.every((v) => tags.includes(v)) && tags.every((v) => currentTags.includes(v));
+        if (!currentIsSameAsNew) {
+          tagsOperation = this.sharedTagsMap.set(cacheKey, [...tags]);
+        }
+      }
+      await Promise.all([setOperation, tagsOperation]);
+    } catch (error) {
+      console.error(
+        "RedisCacheComponentsHandler.set() Error occurred while setting cache entry. The original error was:",
+        error,
+        killContainerOnErrorCount2++
+      );
+      throw error;
+    }
+  }
+  async refreshTags() {
+    await this.assertClientIsReady();
+  }
+  async getExpiration(tags) {
+    try {
+      await this.assertClientIsReady();
+      return this.computeMaxRevalidation(tags || []);
+    } catch (error) {
+      console.error(
+        "RedisCacheComponentsHandler.getExpiration() Error occurred while getting expiration for tags. The original error was:",
+        error
+      );
+      return 0;
+    }
+  }
+  async updateTags(tags, _durations) {
+    try {
+      void _durations;
+      await this.assertClientIsReady();
+      const now = Date.now();
+      const tagsSet = new Set(tags || []);
+      for (const tag of tagsSet) {
+        await this.revalidatedTagsMap.set(tag, now);
+      }
+      const keysToDelete = /* @__PURE__ */ new Set();
+      for (const [key, storedTags] of this.sharedTagsMap.entries()) {
+        if (storedTags.some((tag) => tagsSet.has(tag))) {
+          keysToDelete.add(key);
+        }
+      }
+      if (keysToDelete.size === 0) {
+        return;
+      }
+      const cacheKeys = Array.from(keysToDelete);
+      const fullRedisKeys = cacheKeys.map((key) => `${this.keyPrefix}${key}`);
+      await redisErrorHandler(
+        "RedisCacheComponentsHandler.updateTags(), operation: unlink",
+        this.client.unlink(fullRedisKeys)
+      );
+      const deleteTagsOperation = this.sharedTagsMap.delete(cacheKeys);
+      await deleteTagsOperation;
+    } catch (error) {
+      console.error(
+        "RedisCacheComponentsHandler.updateTags() Error occurred while updating tags. The original error was:",
+        error,
+        killContainerOnErrorCount2++
+      );
+      throw error;
+    }
+  }
+};
+var singletonHandler;
+function getRedisCacheComponentsHandler(options = {}) {
+  if (!singletonHandler) {
+    singletonHandler = new RedisCacheComponentsHandler(options);
+  }
+  return singletonHandler;
+}
+var redisCacheHandler = getRedisCacheComponentsHandler();
+
 // src/index.ts
 var index_default = CachedHandler;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  RedisStringsHandler
+  RedisStringsHandler,
+  getRedisCacheComponentsHandler,
+  redisCacheHandler
 });
 //# sourceMappingURL=index.js.map