3.1.0

Author: AyronK

README.md

@@ -245,7 +245,56 @@ const redisHandler = await createRedisHandler({
 });
 ```
 
-#### Redis Cluster (Experimental)
+#### Custom value serializer
+
+By default, the handler stores each entry as a JSON string (`JSON.stringify` / `JSON.parse`), matching earlier releases. You can plug in your own wire format to shrink payloads (compression), add encryption, or use another encoding-this package does not ship extra codecs so your dependencies stay minimal.
+
+**Contract**
+
+- `serialize(value)` receives the full cache object Next.js passes in (metadata such as `tags`, `lastModified`, `lifespan`, plus the nested `value` payload). It must return a string suitable for Redis `SET`.
+- `deserialize(stored)` receives that string from Redis `GET`. Return a parsed object compatible with the handler, or `null` to treat the key as a miss (stale entries are removed).
+
+The handler normalizes `Buffer` fields inside the payload to strings before `serialize`, and restores buffers after `deserialize`, so a plain `JSON.stringify` / `JSON.parse` round trip remains valid.
+
+**Default export for reuse**
+
+You can import the built-in serializer if you want to wrap or compare behavior:
+
+```js
+import createRedisHandler, {
+  jsonCacheValueSerializer,
+} from "@fortedigital/nextjs-cache-handler/redis-strings";
+```
+
+**Example: gzip + base64**
+
+Useful when cache entries are large text (RSC payloads, HTML). Uses Node’s built-in `zlib`; `gzipSync` / `gunzipSync` run on the server during cache reads and writes-profile if your traffic is very hot.
+
+```js
+import { gzipSync, gunzipSync } from "node:zlib";
+import createRedisHandler from "@fortedigital/nextjs-cache-handler/redis-strings";
+
+const redisCacheHandler = createRedisHandler({
+  client: redisClient,
+  keyPrefix: "nextjs:",
+  valueSerializer: {
+    serialize: (value) => gzipSync(JSON.stringify(value)).toString("base64"),
+    deserialize: (stored) => {
+      const parsed = JSON.parse(
+        gunzipSync(Buffer.from(stored, "base64")).toString("utf-8"),
+      );
+      return parsed;
+    },
+  },
+});
+```
+
+**Operational notes**
+
+- Changing `valueSerializer` (or toggling compression) makes existing Redis keys unreadable until you flush those keys or run a migration; plan a key prefix bump or cache clear on deploy.
+- Tag maps and TTL sidecar hashes are still stored as JSON by the handler; only the main entry value uses your serializer.
+
+#### Redis Cluster
 
 ```js
 import { createCluster } from "@redis/client";
@@ -276,8 +325,6 @@ const redisCacheHandler = createRedisHandler({
 });
 ```
 
-**Note:** Redis Cluster support is currently experimental and may have limitations or unexpected bugs. Use it with caution.
-
 ### Using ioredis
 
 If you prefer using `ioredis` instead of `@redis/client`, you can use the `ioredisAdapter` helper.

examples/redis-minimal/package.json

@@ -14,8 +14,8 @@
   },
   "dependencies": {
     "@fortedigital/nextjs-cache-handler": "workspace:*",
-    "ioredis": "^5.9.3",
-    "next": "16.1.6",
+    "ioredis": "^5.10.1",
+    "next": "16.2.1",
     "react": "19.2.4",
     "react-dom": "19.2.4",
     "redis": "^5.11.0"
@@ -26,7 +26,7 @@
     "@types/react": "19.2.14",
     "@types/react-dom": "19.2.3",
     "eslint": "^9",
-    "eslint-config-next": "16.1.6",
+    "eslint-config-next": "16.2.1",
     "tailwindcss": "^4",
     "typescript": "^5"
   },

packages/nextjs-cache-handler/package.json

@@ -18,7 +18,7 @@
     "next",
     "redis"
   ],
-  "version": "3.0.1",
+  "version": "3.1.0",
   "type": "module",
   "license": "MIT",
   "description": "Next.js cache handlers",
@@ -110,7 +110,7 @@
   },
   "dependencies": {
     "cluster-key-slot": "1.1.2",
-    "lru-cache": "11.2.6",
+    "lru-cache": "11.2.7",
     "p-limit": "^7.3.0"
   },
   "devDependencies": {
@@ -119,17 +119,17 @@
     "@types/node": "22.19.11",
     "eslint": "^8.57.1",
     "eslint-config-prettier": "^9.1.2",
-    "globals": "^16.5.0",
-    "ioredis": "^5.9.3",
-    "jest": "^30.2.0",
+    "globals": "^17.4.0",
+    "ioredis": "^5.10.1",
+    "jest": "^30.3.0",
     "prettier": "^3.8.1",
-    "prettier-plugin-packagejson": "2.5.22",
+    "prettier-plugin-packagejson": "3.0.2",
     "rimraf": "6.1.3",
     "ts-jest": "^29.4.6",
     "tsup": "^8.5.1",
     "tsx": "4.21.0",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.56.0"
+    "typescript-eslint": "^8.57.2"
   },
   "peerDependencies": {
     "@redis/client": ">= 5.8.3",
@@ -145,7 +145,7 @@
     "next16"
   ],
   "optionalDependencies": {
-    "@rollup/rollup-linux-x64-gnu": "^4.59.0"
+    "@rollup/rollup-linux-x64-gnu": "^4.60.0"
   },
   "engines": {
     "node": ">=22.0.0"

packages/nextjs-cache-handler/src/functions/nesh-classic-cache.ts

@@ -4,9 +4,10 @@ import { Revalidate } from "../handlers/cache-handler.types";
 import { workAsyncStorage } from "next/dist/server/app-render/work-async-storage.external.js";
 import type { IncrementalCache } from "next/dist/server/lib/incremental-cache";
 import { CacheHandler } from "../handlers/cache-handler";
-import { CACHE_ONE_YEAR } from "next/dist/lib/constants";
 import { CachedRouteKind } from "next/dist/server/response-cache";
 
+const CACHE_ONE_YEAR = 31536000;
+
 declare global {
   var __incrementalCache: IncrementalCache | undefined;
 }

packages/nextjs-cache-handler/src/instrumentation/register-initial-cache.ts

@@ -2,7 +2,6 @@ import { promises as fsPromises } from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import { PRERENDER_MANIFEST, SERVER_DIRECTORY } from "next/constants.js";
-import { CACHE_ONE_YEAR } from "next/dist/lib/constants.js";
 import type { PrerenderManifest } from "next/dist/build";
 import {
   CachedFetchValue,
@@ -15,6 +14,8 @@ import { getTagsFromHeaders } from "../helpers/getTagsFromHeaders";
 import { Revalidate } from "../handlers/cache-handler.types";
 import pLimit from "p-limit";
 
+const CACHE_ONE_YEAR = 31536000;
+
 type CacheHandlerType = typeof import("../handlers/cache-handler").CacheHandler;
 
 type NextRouteMetadata = {