@trieb.work/nextjs-turbo-redis-cache 1.10.0-beta.14 → 1.11.0-beta.1

package/.github/workflows/ci.yml

@@ -25,11 +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
+        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:
@@ -42,7 +46,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v6
         with:
-          node-version: '20'
+          node-version: '22'
           cache: 'pnpm'
 
       - name: Install dependencies
@@ -78,18 +82,30 @@ jobs:
           SKIP_BUILD: true
           NEXT_TEST_APP: ${{ matrix.next-test-app }}
 
-      - name: Install Playwright browsers (Next 16 only)
-        if: matrix.next-test-app == 'next-app-16-0-3'
+      - 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: matrix.next-test-app == 'next-app-16-0-3'
+      - 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
-        if: github.event_name == 'pull_request'
+        if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
         uses: kcjpop/coverage-comments@v2.2
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}

package/CHANGELOG.md

@@ -1,107 +1,19 @@
-# [1.10.0-beta.14](https://github.com/trieb-work/nextjs-turbo-redis-cache/compare/v1.10.0-beta.13...v1.10.0-beta.14) (2025-12-27)
+# [1.11.0-beta.1](https://github.com/trieb-work/nextjs-turbo-redis-cache/compare/v1.10.0...v1.11.0-beta.1) (2025-12-30)
 
 
-### Bug Fixes
-
-* remove extensive debugging and simplify npm publish step in release workflow ([d3b7aa9](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/d3b7aa9fa13d9ff65e2b34e1e49433507cfb9cb2))
-
-# [1.10.0-beta.13](https://github.com/trieb-work/nextjs-turbo-redis-cache/compare/v1.10.0-beta.12...v1.10.0-beta.13) (2025-12-27)
-
-
-### Bug Fixes
-
-* add comprehensive debugging and .npmrc configuration for npm trusted publishing ([8d4fabb](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/8d4fabb02062a7a771693277909555671e810835))
-
-# [1.10.0-beta.12](https://github.com/trieb-work/nextjs-turbo-redis-cache/compare/v1.10.0-beta.11...v1.10.0-beta.12) (2025-12-27)
-
-
-### Bug Fixes
-
-* implement OIDC token exchange for npm trusted publishing in release workflow ([3b3cea1](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/3b3cea152dfb183e918dac1b34c6a8277c300474))
-
-# [1.10.0-beta.11](https://github.com/trieb-work/nextjs-turbo-redis-cache/compare/v1.10.0-beta.10...v1.10.0-beta.11) (2025-12-27)
-
-
-### Bug Fixes
-
-* add diagnostics step to debug OIDC and npm configuration in release workflow ([6a7f3cf](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/6a7f3cf7cda23d57acb34d3bb4c4dd6ab7103ca7))
-
-# [1.10.0-beta.10](https://github.com/trieb-work/nextjs-turbo-redis-cache/compare/v1.10.0-beta.9...v1.10.0-beta.10) (2025-12-27)
-
-
-### Bug Fixes
-
-* add provenance, public access, and verbose logging to npm publish command ([2fccf3d](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/2fccf3d12c899e5aee38ea5d7c0cdce22dd83ce4))
-
-# [1.10.0-beta.9](https://github.com/trieb-work/nextjs-turbo-redis-cache/compare/v1.10.0-beta.8...v1.10.0-beta.9) (2025-12-27)
-
-
-### Bug Fixes
-
-* add git+ prefix to repository URL in package.json ([70f94df](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/70f94dff5059808eb4a2376950f3bb9fecb4511e))
-
-# [1.10.0-beta.8](https://github.com/trieb-work/nextjs-turbo-redis-cache/compare/v1.10.0-beta.7...v1.10.0-beta.8) (2025-12-27)
-
-
-### Bug Fixes
-
-* disable semantic-release npm publishing and add manual npm publish step with trusted publishing ([4cbf99d](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/4cbf99de560a6a466b5d10f945bd9640356ef444))
-
-# [1.10.0-beta.7](https://github.com/trieb-work/nextjs-turbo-redis-cache/compare/v1.10.0-beta.6...v1.10.0-beta.7) (2025-12-26)
-
-
-### Bug Fixes
-
-* remove empty auth token environment variables from release workflow ([8d4e87b](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/8d4e87b301842842cd3d0c0a8cb8401dbf100fa9))
-
-# [1.10.0-beta.6](https://github.com/trieb-work/nextjs-turbo-redis-cache/compare/v1.10.0-beta.5...v1.10.0-beta.6) (2025-12-26)
-
-
-### Bug Fixes
-
-* upgrade semantic-release and related dependencies to v25 ([63fd812](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/63fd812bc0815aa5155619faf9b36b9287daac21))
-* use pnpm exec instead of pnpx for semantic-release command ([ca310c0](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/ca310c0e1b4150052787eba1709152d606d2d76d))
-
-# [1.10.0-beta.5](https://github.com/trieb-work/nextjs-turbo-redis-cache/compare/v1.10.0-beta.4...v1.10.0-beta.5) (2025-12-26)
-
-
-### Bug Fixes
-
-* remove registry-url and clear auth tokens in release workflow ([b0d9edb](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/b0d9edb4e8efa37500a4dfe4054a24f55582e60e))
-
-# [1.10.0-beta.4](https://github.com/trieb-work/nextjs-turbo-redis-cache/compare/v1.10.0-beta.3...v1.10.0-beta.4) (2025-12-26)
-
-
-### Bug Fixes
-
-* trigger beta release ([724ecbb](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/724ecbb6d76697818a2c6a863c98e144eed049d2))
-
-# [1.10.0-beta.3](https://github.com/trieb-work/nextjs-turbo-redis-cache/compare/v1.10.0-beta.2...v1.10.0-beta.3) (2025-12-26)
-
-
-### Bug Fixes
-
-* configure npm provenance in package.json publishConfig ([83a3017](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/83a301797396e98b739db199bfb3e97ee1c8565e))
-
-# [1.10.0-beta.2](https://github.com/trieb-work/nextjs-turbo-redis-cache/compare/v1.10.0-beta.1...v1.10.0-beta.2) (2025-12-26)
-
-
-### Bug Fixes
+### Features
 
-* trigger beta release ([432b58f](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/432b58f661db20e5a8302d54679b16cc33a6dfb6))
+* add Next.js 16.0.3 integration test environment and build artifacts for cache components ([f2b3088](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/f2b3088c5845865cb69e5ee691cd09ede5735119))
+* add Next.js 16.0.3 integration test environment and build artifacts for cache components ([01fb22a](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/01fb22a9ae0fbbb6fba44bb225ab46fdcc009a85))
+* cache components lab + Next.js 16.1.x support ([be2e9b3](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/be2e9b3b7af441df112fc83483994877a4415443))
 
-# [1.10.0-beta.1](https://github.com/trieb-work/nextjs-turbo-redis-cache/compare/v1.9.1...v1.10.0-beta.1) (2025-12-26)
+# [1.10.0](https://github.com/trieb-work/nextjs-turbo-redis-cache/compare/v1.9.1...v1.10.0) (2025-12-27)
 
 
 ### Bug Fixes
 
-* avoid overlapping redis reconnects ([4da291f](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/4da291f1a62ef8ffd9a8528640ee57b1367d0e25))
 * cleanup ([c948fdf](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/c948fdfe0e6b5f70edc985b3cdda9cf2f002633a))
 * folder structure ([93356fd](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/93356fd567c0f05fad92d3443da77216fd2cc28d))
-* just testing around ([09bd26d](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/09bd26dc7b328945f11818a11446b3e5dd86c943))
-* remove not needed attributes ([6c11e0d](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/6c11e0d574e6ae8d98c60f71ea70070415de9de7))
-* testing with npm ([fa7ecb0](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/fa7ecb0283c2611918a3f780bc0c87cf2b28d5db))
-* trigger beta release ([62ea418](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/62ea4182b65fac53f23a93418b9f4650ab717b60))
 
 
 ### Features

package/README.md

@@ -214,6 +214,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:
@@ -230,6 +236,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.
@@ -238,6 +252,86 @@ 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.
+
+### 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 { 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 { 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 { 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 { RedisStringsHandler, CachedHandler as default, getRedisCacheComponentsHandler, redisCacheHandler };