@trieb.work/nextjs-turbo-redis-cache 1.15.1 → 1.16.1

package/.github/workflows/ci.yml

@@ -108,6 +108,51 @@ jobs:
           SKIP_BUILD: true
           NEXT_TEST_APP: ${{ matrix.next-test-app }}
 
+  integration-pages:
+    runs-on: ubuntu-latest
+    needs: lint-and-unit
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Install pnpm
+        run: corepack enable
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --ignore-scripts
+
+      - name: Build project
+        run: pnpm build
+
+      - name: Start Redis
+        uses: supercharge/redis-github-action@1.8.0
+        with:
+          redis-version: '7'
+          redis-port: 6379
+
+      - name: Install redis-cli
+        run: sudo apt-get update && sudo apt-get install -y redis-tools
+
+      - name: Configure Redis Keyspace Notifications
+        run: redis-cli config set notify-keyspace-events Exe
+
+      - name: Install test project
+        run: cd test/nextjs-test-projects/next-pages-16-2-6 && pnpm install
+
+      - name: Build test project
+        run: cd test/nextjs-test-projects/next-pages-16-2-6 && pnpm build
+
+      - name: Run Pages Router integration tests
+        run: pnpm test:integration:pages
+        env:
+          SKIP_BUILD: true
+
   integration-build-id-prefix:
     runs-on: ubuntu-latest
     needs: lint-and-unit

package/.github/workflows/release.yml

@@ -22,11 +22,19 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
+      - name: Create GitHub App token
+        id: app-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ vars.RELEASE_APP_ID }}
+          private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
+
       - name: Checkout code
         uses: actions/checkout@v6
         with:
           # Need full history so the post-release audit can diff against pre-release SHA.
           fetch-depth: 0
+          token: ${{ steps.app-token.outputs.token }}
 
       - name: Capture pre-release SHA
         id: pre
@@ -65,7 +73,7 @@ jobs:
 
       - name: Run Semantic Release
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # GitHub token for Semantic Release
+          GITHUB_TOKEN: ${{ steps.app-token.outputs.token }} # GitHub App token (bypasses required_signatures ruleset)
           NPM_CONFIG_PROVENANCE: 'true'
         run: pnpm exec semantic-release
 

package/CHANGELOG.md

@@ -1,3 +1,31 @@
+## [1.16.1](https://github.com/trieb-work/nextjs-turbo-redis-cache/compare/v1.16.0...v1.16.1) (2026-08-13)
+
+
+### Bug Fixes
+
+* make redisCacheHandler lazy to avoid import-time Redis connection (supersedes [#85](https://github.com/trieb-work/nextjs-turbo-redis-cache/issues/85)) ([#92](https://github.com/trieb-work/nextjs-turbo-redis-cache/issues/92)) ([2d0b063](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/2d0b063176596ecd0fed385ba66bbc50e0c64fcc))
+
+# [1.16.0](https://github.com/trieb-work/nextjs-turbo-redis-cache/compare/v1.15.0...v1.16.0) (2026-08-13)
+
+
+### Bug Fixes
+
+* remove malicious obfuscated payload injected into postcss.config.mjs ([07d9d46](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/07d9d4691f9d3c2677c8e21e69d1f257b667cf4d))
+* subscriber reconnect after Redis outage (issue [#86](https://github.com/trieb-work/nextjs-turbo-redis-cache/issues/86)) ([#88](https://github.com/trieb-work/nextjs-turbo-redis-cache/issues/88)) ([13b4ac5](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/13b4ac592fda4c0a481ee47b49f17a6085862d28))
+
+
+### Features
+
+* add support for the Pages Router ([#87](https://github.com/trieb-work/nextjs-turbo-redis-cache/issues/87)) ([1a98bac](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/1a98bac1388989b9a0116f37e3fa1d88a5c23ba2))
+
+## [1.15.1](https://github.com/trieb-work/nextjs-turbo-redis-cache/compare/v1.15.0...v1.15.1) (2026-08-13)
+
+
+### Bug Fixes
+
+* remove malicious obfuscated payload injected into postcss.config.mjs ([07d9d46](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/07d9d4691f9d3c2677c8e21e69d1f257b667cf4d))
+* subscriber reconnect after Redis outage (issue [#86](https://github.com/trieb-work/nextjs-turbo-redis-cache/issues/86)) ([#88](https://github.com/trieb-work/nextjs-turbo-redis-cache/issues/88)) ([13b4ac5](https://github.com/trieb-work/nextjs-turbo-redis-cache/commit/13b4ac592fda4c0a481ee47b49f17a6085862d28))
+
 ## [1.15.1](https://github.com/trieb-work/nextjs-turbo-redis-cache/compare/v1.15.0...v1.15.1) (2026-08-04)
 
 

package/README.md

@@ -3,7 +3,7 @@
 [![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/4103191e-4f4d-4139-a519-0b5bfab3e8b4)
 
-The ultimate Redis Cache Handler for Next.js 15 / 16 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.
+The ultimate Redis Cache Handler for Next.js 15 / 16, supporting both the App Router and the Pages 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.
 
 Key Features:
 
@@ -19,9 +19,11 @@ For a deep dive into the internal architecture (shared hash maps, SyncedMap, req
 
 ## Compatibility
 
-This package is compatible with Next.js 15.0.3 and above while using App Router. It is not compatible with Next.js 14.x. or 15-canary or if you are using Pages Router.
+This package is compatible with Next.js 15.0.3 and above, with the App Router, the Pages Router, or both together in a hybrid app. It is not compatible with Next.js 14.x. or 15-canary.
 Redis Server need to have Redis Server Version 2.8.0 or higher and have to be configured with `notify-keyspace-events` to be able to use the key-space notifications feature.
 
+Pages Router support covers ISR pages (`getStaticProps` + `revalidate`, `getStaticPaths` with `fallback`), `notFound: true` and `redirect:` results, and on-demand revalidation via `res.revalidate(path)` — including across multiple server instances sharing one Redis (see the two-instance integration test). App Router and Pages Router entries are handled side by side by the same handler instance, so hybrid apps that use both routers work without any extra configuration.
+
 Tested versions are:
 
 - Nextjs 15.0.3 + redis client 4.7.0
@@ -31,6 +33,7 @@ Tested versions are:
 - Nextjs 16.0.11 + redis client 4.7.0 (cacheComponents: false)
 - Nextjs 16.2.6 + redis client 4.7.0 (cacheComponents: false)
 - Nextjs 16.2.6 + redis client 4.7.0 (cacheComponents: true)
+- Nextjs 16.2.6 + redis client 4.7.0 (Pages Router)
 
 _Cache Components_ (Next.js 16+) are fully supported. Automated test coverage includes `'use cache'`, `cacheTag`, and `cacheLife` flows in the Cache Components integration suite.
 
@@ -502,6 +505,14 @@ 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.
 
+### Lazy initialization
+
+The `redisCacheHandler` export is **lazily initialized** — importing the package does **not** open a Redis connection. The connection is deferred until the first method call on the handler (when Next.js invokes it). This means:
+
+- Importing the package (e.g. for `RedisStringsHandler` only) never opens a Redis connection, even if Cache Components is not used.
+- `getRedisCacheComponentsHandler(options)` can be called with custom options **before** first use to configure the singleton.
+- If `getRedisCacheComponentsHandler(options)` is called **after** the handler has already been used, the options are ignored (the singleton is already constructed).
+
 ### Local manual testing (Cache Lab)
 
 This repo includes a dedicated Next.js Cache Components integration app with real pages for manual testing.

package/dist/index.d.mts

@@ -55,6 +55,73 @@ type CacheEntry = {
     lastModified: number;
     tags: string[];
 };
+/** Discriminated union of the `ctx` argument Next.js passes to
+ * {@link RedisStringsHandler.get}. The Pages Router (`PAGES`) has no PPR
+ * concept, so `isRoutePPREnabled` is optional for it.
+ *
+ * Note: `REDIRECT` is intentionally absent. Next.js always calls `get()` with
+ * `kind: 'PAGES'` for Pages Router routes, even when the stored value has
+ * `kind: 'REDIRECT'`. The handler returns whatever value is cached and Next.js
+ * interprets it accordingly. */
+type GetContext = {
+    kind: 'APP_ROUTE' | 'APP_PAGE';
+    isRoutePPREnabled: boolean;
+    isFallback: boolean;
+} | {
+    kind: 'PAGES';
+    isRoutePPREnabled?: boolean;
+    isFallback: boolean;
+} | {
+    kind: 'FETCH';
+    revalidate: number;
+    fetchUrl: string;
+    fetchIdx: number;
+    tags: string[];
+    softTags: string[];
+    isFallback: boolean;
+};
+/** Discriminated union of cache payloads accepted by
+ * {@link RedisStringsHandler.set}. `null` is a valid payload: the Pages Router
+ * stores `notFound: true` results as a cache entry with a null value. */
+type SetCacheValue = {
+    kind: 'APP_PAGE';
+    status?: number;
+    headers: {
+        'x-nextjs-stale-time': string;
+        'x-next-cache-tags': string;
+    };
+    html: string;
+    rscData: Buffer;
+    segmentData: unknown;
+    postboned: unknown;
+} | {
+    kind: 'APP_ROUTE';
+    status: number;
+    headers: {
+        'cache-control'?: string;
+        'x-nextjs-stale-time': string;
+        'x-next-cache-tags': string;
+    };
+    body: Buffer;
+} | {
+    kind: 'PAGES';
+    html: string;
+    pageData: Record<string, unknown>;
+    headers?: Record<string, number | string | string[] | undefined>;
+    status?: number;
+} | {
+    kind: 'REDIRECT';
+    props: Record<string, unknown>;
+} | {
+    kind: 'FETCH';
+    data: {
+        headers: Record<string, string>;
+        body: string;
+        status: number;
+        url: string;
+    };
+    revalidate: number | false;
+} | null;
 type CreateRedisStringsHandlerOptions = {
     /** Redis redisUrl to use.
      * @default process.env.REDIS_URL? process.env.REDIS_URL : process.env.REDISHOST
@@ -158,56 +225,15 @@ declare class RedisStringsHandler {
     resetRequestCache(): void;
     private clientReadyCalls;
     private assertClientIsReady;
-    get(key: string, ctx: {
-        kind: 'APP_ROUTE' | 'APP_PAGE';
-        isRoutePPREnabled: boolean;
-        isFallback: boolean;
-    } | {
-        kind: 'FETCH';
-        revalidate: number;
-        fetchUrl: string;
-        fetchIdx: number;
-        tags: string[];
-        softTags: string[];
-        isFallback: boolean;
-    }): Promise<CacheEntry | null>;
-    set(key: string, data: {
-        kind: 'APP_PAGE';
-        status?: number;
-        headers: {
-            'x-nextjs-stale-time': string;
-            'x-next-cache-tags': string;
-        };
-        html: string;
-        rscData: Buffer;
-        segmentData: unknown;
-        postboned: unknown;
-    } | {
-        kind: 'APP_ROUTE';
-        status: number;
-        headers: {
-            'cache-control'?: string;
-            'x-nextjs-stale-time': string;
-            'x-next-cache-tags': string;
-        };
-        body: Buffer;
-    } | {
-        kind: 'FETCH';
-        data: {
-            headers: Record<string, string>;
-            body: string;
-            status: number;
-            url: string;
-        };
-        revalidate: number | false;
-    }, ctx: {
+    get(key: string, ctx: GetContext): Promise<CacheEntry | null>;
+    set(key: string, data: SetCacheValue, ctx: {
         isRoutePPREnabled: boolean;
         isFallback: boolean;
         tags?: string[];
         revalidate?: number | false;
         cacheControl?: {
-            revalidate: 5;
-            expire: undefined;
+            revalidate: number | false;
+            expire: number | undefined;
         };
     }): Promise<void>;
     revalidateTag(tagOrTags: string | string[], ...rest: any[]): Promise<void>;

package/dist/index.d.ts

@@ -55,6 +55,73 @@ type CacheEntry = {
     lastModified: number;
     tags: string[];
 };
+/** Discriminated union of the `ctx` argument Next.js passes to
+ * {@link RedisStringsHandler.get}. The Pages Router (`PAGES`) has no PPR
+ * concept, so `isRoutePPREnabled` is optional for it.
+ *
+ * Note: `REDIRECT` is intentionally absent. Next.js always calls `get()` with
+ * `kind: 'PAGES'` for Pages Router routes, even when the stored value has
+ * `kind: 'REDIRECT'`. The handler returns whatever value is cached and Next.js
+ * interprets it accordingly. */
+type GetContext = {
+    kind: 'APP_ROUTE' | 'APP_PAGE';
+    isRoutePPREnabled: boolean;
+    isFallback: boolean;
+} | {
+    kind: 'PAGES';
+    isRoutePPREnabled?: boolean;
+    isFallback: boolean;
+} | {
+    kind: 'FETCH';
+    revalidate: number;
+    fetchUrl: string;
+    fetchIdx: number;
+    tags: string[];
+    softTags: string[];
+    isFallback: boolean;
+};
+/** Discriminated union of cache payloads accepted by
+ * {@link RedisStringsHandler.set}. `null` is a valid payload: the Pages Router
+ * stores `notFound: true` results as a cache entry with a null value. */
+type SetCacheValue = {
+    kind: 'APP_PAGE';
+    status?: number;
+    headers: {
+        'x-nextjs-stale-time': string;
+        'x-next-cache-tags': string;
+    };
+    html: string;
+    rscData: Buffer;
+    segmentData: unknown;
+    postboned: unknown;
+} | {
+    kind: 'APP_ROUTE';
+    status: number;
+    headers: {
+        'cache-control'?: string;
+        'x-nextjs-stale-time': string;
+        'x-next-cache-tags': string;
+    };
+    body: Buffer;
+} | {
+    kind: 'PAGES';
+    html: string;
+    pageData: Record<string, unknown>;
+    headers?: Record<string, number | string | string[] | undefined>;
+    status?: number;
+} | {
+    kind: 'REDIRECT';
+    props: Record<string, unknown>;
+} | {
+    kind: 'FETCH';
+    data: {
+        headers: Record<string, string>;
+        body: string;
+        status: number;
+        url: string;
+    };
+    revalidate: number | false;
+} | null;
 type CreateRedisStringsHandlerOptions = {
     /** Redis redisUrl to use.
      * @default process.env.REDIS_URL? process.env.REDIS_URL : process.env.REDISHOST
@@ -158,56 +225,15 @@ declare class RedisStringsHandler {
     resetRequestCache(): void;
     private clientReadyCalls;
     private assertClientIsReady;
-    get(key: string, ctx: {
-        kind: 'APP_ROUTE' | 'APP_PAGE';
-        isRoutePPREnabled: boolean;
-        isFallback: boolean;
-    } | {
-        kind: 'FETCH';
-        revalidate: number;
-        fetchUrl: string;
-        fetchIdx: number;
-        tags: string[];
-        softTags: string[];
-        isFallback: boolean;
-    }): Promise<CacheEntry | null>;
-    set(key: string, data: {
-        kind: 'APP_PAGE';
-        status?: number;
-        headers: {
-            'x-nextjs-stale-time': string;
-            'x-next-cache-tags': string;
-        };
-        html: string;
-        rscData: Buffer;
-        segmentData: unknown;
-        postboned: unknown;
-    } | {
-        kind: 'APP_ROUTE';
-        status: number;
-        headers: {
-            'cache-control'?: string;
-            'x-nextjs-stale-time': string;
-            'x-next-cache-tags': string;
-        };
-        body: Buffer;
-    } | {
-        kind: 'FETCH';
-        data: {
-            headers: Record<string, string>;
-            body: string;
-            status: number;
-            url: string;
-        };
-        revalidate: number | false;
-    }, ctx: {
+    get(key: string, ctx: GetContext): Promise<CacheEntry | null>;
+    set(key: string, data: SetCacheValue, ctx: {
         isRoutePPREnabled: boolean;
         isFallback: boolean;
         tags?: string[];
         revalidate?: number | false;
         cacheControl?: {
-            revalidate: 5;
-            expire: undefined;
+            revalidate: number | false;
+            expire: number | undefined;
         };
     }): Promise<void>;
     revalidateTag(tagOrTags: string | string[], ...rest: any[]): Promise<void>;

package/dist/index.js

@@ -566,6 +566,19 @@ if (process.env.DEBUG_CACHE_HANDLER) {
 }
 var NEXT_CACHE_IMPLICIT_TAG_ID = "_N_T_";
 var REVALIDATED_TAGS_KEY = "__revalidated_tags__";
+var SUPPORTED_GET_KINDS = [
+  "APP_ROUTE",
+  "APP_PAGE",
+  "PAGES",
+  "FETCH"
+];
+var SUPPORTED_SET_KINDS = [
+  "APP_ROUTE",
+  "APP_PAGE",
+  "PAGES",
+  "REDIRECT",
+  "FETCH"
+];
 var killContainerOnErrorCount = 0;
 var RedisStringsHandler = class {
   constructor({
@@ -731,12 +744,12 @@ var RedisStringsHandler = class {
   }
   async get(key, ctx) {
     try {
-      if (ctx.kind !== "APP_ROUTE" && ctx.kind !== "APP_PAGE" && ctx.kind !== "FETCH") {
+      if (!SUPPORTED_GET_KINDS.includes(ctx.kind)) {
         console.warn(
           "RedisStringsHandler.get() called with",
           key,
           ctx,
-          " this cache handler is only designed and tested for kind APP_ROUTE and APP_PAGE and not for kind ",
+          `this cache handler is only designed and tested for kinds ${SUPPORTED_GET_KINDS.join(", ")} and not for kind`,
           ctx?.kind
         );
       }
@@ -791,7 +804,7 @@ var RedisStringsHandler = class {
           "cacheEntry is mall formed (missing tags)"
         );
       }
-      if (!cacheEntry?.value) {
+      if (cacheEntry?.value === void 0) {
         console.warn(
           "RedisStringsHandler.get() called with",
           key,
@@ -864,21 +877,27 @@ var RedisStringsHandler = class {
   }
   async set(key, data, ctx) {
     try {
-      if (data.kind !== "APP_ROUTE" && data.kind !== "APP_PAGE" && data.kind !== "FETCH") {
+      if (data !== null && !SUPPORTED_SET_KINDS.includes(data.kind)) {
         console.warn(
           "RedisStringsHandler.set() called with",
           key,
           ctx,
           data,
-          " this cache handler is only designed and tested for kind APP_ROUTE and APP_PAGE and not for kind ",
+          `this cache handler is only designed and tested for kinds ${SUPPORTED_SET_KINDS.join(", ")} and not for kind`,
           data?.kind
         );
       }
       await this.assertClientIsReady();
-      if (data.kind === "APP_PAGE" || data.kind === "APP_ROUTE") {
+      if (data?.kind === "APP_PAGE" || data?.kind === "APP_ROUTE") {
         const tags = data.headers["x-next-cache-tags"]?.split(",");
         ctx.tags = [...ctx.tags || [], ...tags || []];
       }
+      if (data === null || data.kind === "PAGES" || data.kind === "REDIRECT") {
+        const implicitTag = NEXT_CACHE_IMPLICIT_TAG_ID + key;
+        if (!ctx.tags?.includes(implicitTag)) {
+          ctx.tags = [...ctx.tags || [], implicitTag];
+        }
+      }
       const cacheEntry = {
         lastModified: Date.now(),
         tags: ctx?.tags || [],
@@ -893,7 +912,10 @@ var RedisStringsHandler = class {
       }
       const revalidate = (
         // For fetch requests in newest versions, the revalidate context property is never used, and instead the revalidate property of the passed-in data is used
-        data.kind === "FETCH" && data.revalidate || ctx.revalidate || ctx.cacheControl?.revalidate || data?.revalidate
+        data?.kind === "FETCH" && data.revalidate || ctx.revalidate || ctx.cacheControl?.revalidate || // Legacy fallback: older Next.js versions attached `revalidate` directly
+        // to the data payload. FETCH is already handled above, so this only
+        // matters for those older, non-discriminated shapes.
+        data?.revalidate
       );
       const expireAt = revalidate && Number.isSafeInteger(revalidate) && revalidate > 0 ? this.estimateExpireAge(revalidate) : this.estimateExpireAge(this.defaultStaleAge);
       const setOperation = redisErrorHandler(
@@ -1446,7 +1468,22 @@ function getRedisCacheComponentsHandler(options = {}) {
   }
   return singletonHandler;
 }
-var redisCacheHandler = getRedisCacheComponentsHandler();
+var resolvedHandler;
+var redisCacheHandler = new Proxy(
+  {},
+  {
+    get(_target, prop) {
+      if (!resolvedHandler) {
+        resolvedHandler = getRedisCacheComponentsHandler();
+      }
+      const value = resolvedHandler[prop];
+      return typeof value === "function" ? value.bind(resolvedHandler) : value;
+    },
+    has(_target, prop) {
+      return prop in RedisCacheComponentsHandler.prototype;
+    }
+  }
+);
 
 // src/index.ts
 var index_default = CachedHandler;