Prepared full example

Author: AyronK

README.md

@@ -35,7 +35,9 @@ If you need the full Redis package:
 **Before (1.x.x):**
 
 ```js
-const { Next15CacheHandler } = require("@fortedigital/nextjs-cache-handler/next-15-cache-handler");
+const {
+  Next15CacheHandler,
+} = require("@fortedigital/nextjs-cache-handler/next-15-cache-handler");
 module.exports = new Next15CacheHandler();
 ```
 
@@ -106,7 +108,7 @@ If upgrading from Next 14 or earlier, **flush your Redis cache**. Cache formats
 
 ## Next 15 Support
 
-`@neshca/cache-handler` does not support Next.js 15+. Prior to 2.0.0, this package provided wrappers and enhancements. 
+`@neshca/cache-handler` does not support Next.js 15+. Prior to 2.0.0, this package provided wrappers and enhancements.
 From version 2.0.0 onward, `@fortedigital/nextjs-cache-handler` is a standalone solution with no dependency on `@neshca/cache-handler`.
 
 We aim to keep up with new Next.js releases and will introduce major changes with appropriate version bumps.
@@ -276,13 +278,19 @@ const bufferStringDecorator =
 
 ### 2.x.x
 
+#### Full example
+
+`./examples/redis-minimal`
+
+#### Example `cache-handler.js`.
+
 ```js
 const { createClient } = require("redis");
 const { PHASE_PRODUCTION_BUILD } = require("next/constants");
 const createCompositeHandler =
   require("@fortedigital/nextjs-cache-handler/composite").default;
 const createRedisHandler =
-  require("@fortedigital/nextjs-cache-handler/buffer-string-decorator").default;
+  require("@fortedigital/nextjs-cache-handler/redis-strings").default;
 const createLruHandler =
   require("@fortedigital/nextjs-cache-handler/local-lru").default;
 const { CacheHandler } = require("@fortedigital/nextjs-cache-handler");

examples/redis-minimal/.env

@@ -0,0 +1,3 @@
+NEXT_PRIVATE_DEBUG_CACHE="1"
+REDIS_URL="redis://localhost:6379"
+REDIS_SINGLE_CONNECTION=true

examples/redis-minimal/.gitignore

@@ -0,0 +1,38 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

examples/redis-minimal/README.md

@@ -0,0 +1,36 @@
+This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+
+## Getting Started
+
+First, run the development server:
+
+```bash
+npm run dev
+# or
+yarn dev
+# or
+pnpm dev
+# or
+bun dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+
+You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+
+This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+
+## Learn More
+
+To learn more about Next.js, take a look at the following resources:
+
+- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
+- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+
+You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+
+## Deploy on Vercel
+
+The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+
+Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.

examples/redis-minimal/cache-handler.mjs

@@ -0,0 +1,115 @@
+import { createClient } from "redis";
+import { PHASE_PRODUCTION_BUILD } from "next/constants.js";
+import { CacheHandler } from "@fortedigital/nextjs-cache-handler";
+import createLruHandler from "@fortedigital/nextjs-cache-handler/local-lru";
+import createRedisHandler from "@fortedigital/nextjs-cache-handler/redis-strings";
+import createCompositeHandler from "@fortedigital/nextjs-cache-handler/composite";
+
+const isSingleConnectionModeEnabled = !!process.env.REDIS_SINGLE_CONNECTION;
+
+async function setupRedisClient() {
+  if (PHASE_PRODUCTION_BUILD !== process.env.NEXT_PHASE) {
+    try {
+      const redisClient = createClient({
+        url: process.env.REDIS_URL,
+        pingInterval: 10000,
+      });
+
+      redisClient.on("error", (e) => {
+        if (process.env.NEXT_PRIVATE_DEBUG_CACHE !== undefined) {
+          console.warn("Redis error", e);
+        }
+        if (isSingleConnectionModeEnabled) {
+          global.cacheHandlerConfig = null;
+          global.cacheHandlerConfigPromise = null;
+        }
+      });
+
+      console.info("Connecting Redis client...");
+      await redisClient.connect();
+      console.info("Redis client connected.");
+
+      if (!redisClient.isReady) {
+        console.error("Failed to initialize caching layer.");
+      }
+
+      return redisClient;
+    } catch (error) {
+      console.warn("Failed to connect Redis client:", error);
+      if (redisClient) {
+        try {
+          redisClient.destroy();
+        } catch (e) {
+          console.error(
+            "Failed to quit the Redis client after failing to connect.",
+            e
+          );
+        }
+      }
+    }
+  }
+
+  return null;
+}
+
+async function createCacheConfig() {
+  const redisClient = await setupRedisClient();
+  const lruCache = createLruHandler();
+
+  if (!redisClient) {
+    const config = { handlers: [lruCache] };
+    if (isSingleConnectionModeEnabled) {
+      global.cacheHandlerConfigPromise = null;
+      global.cacheHandlerConfig = config;
+    }
+    return config;
+  }
+
+  const redisCacheHandler = createRedisHandler({
+    client: redisClient,
+    keyPrefix: "nextjs:",
+  });
+
+  const config = {
+    handlers: [
+      createCompositeHandler({
+        handlers: [lruCache, redisCacheHandler],
+        setStrategy: (ctx) => (ctx?.tags.includes("memory-cache") ? 0 : 1),
+      }),
+    ],
+  };
+
+  if (isSingleConnectionModeEnabled) {
+    global.cacheHandlerConfigPromise = null;
+    global.cacheHandlerConfig = config;
+  }
+
+  return config;
+}
+
+CacheHandler.onCreation(() => {
+  if (isSingleConnectionModeEnabled) {
+    if (global.cacheHandlerConfig) {
+      return global.cacheHandlerConfig;
+    }
+    if (global.cacheHandlerConfigPromise) {
+      return global.cacheHandlerConfigPromise;
+    }
+  }
+
+  if (process.env.NODE_ENV === "development") {
+    const config = { handlers: [createLruHandler()] };
+    if (isSingleConnectionModeEnabled) {
+      global.cacheHandlerConfig = config;
+    }
+    return config;
+  }
+
+  const promise = createCacheConfig();
+  if (isSingleConnectionModeEnabled) {
+    global.cacheHandlerConfigPromise = promise;
+  }
+  return promise;
+});
+
+export default CacheHandler;

examples/redis-minimal/eslint.config.mjs

@@ -0,0 +1,16 @@
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { FlatCompat } from "@eslint/eslintrc";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const compat = new FlatCompat({
+  baseDirectory: __dirname,
+});
+
+const eslintConfig = [
+  ...compat.extends("next/core-web-vitals", "next/typescript"),
+];
+
+export default eslintConfig;

examples/redis-minimal/next.config.ts

@@ -0,0 +1,11 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  cacheHandler:
+    process.env.NODE_ENV === "production"
+      ? require.resolve("./cache-handler.mjs")
+      : undefined,
+  cacheMaxMemorySize: 0, // disable default in-memory caching
+};
+
+export default nextConfig;