Fixes fetch cache writing to file system allowing instrumentation to prepopulate it. (#65)

* Enables fetch cache writing

Adds functionality to write fetch cache data to the file system, allowing for persistent storage of fetched data.

* Adds ISR example

* PPR example

Author: AyronK

examples/redis-minimal/next.config.ts

@@ -6,6 +6,9 @@ const nextConfig: NextConfig = {
       ? require.resolve("./cache-handler.mjs")
       : undefined,
   cacheMaxMemorySize: 0, // disable default in-memory caching
+  experimental: {
+    ppr: "incremental",
+  },
 };
 
 export default nextConfig;

examples/redis-minimal/package-lock.json

@@ -14,7 +14,7 @@
   },
   "dependencies": {
     "@fortedigital/nextjs-cache-handler": "^2.0.2",
-    "next": "15.4.3",
+    "next": "^15.5.1-canary.7",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "redis": "^5.6.1"
@@ -25,7 +25,7 @@
     "@types/node": "^24",
     "@types/react": "^19",
     "@types/react-dom": "^19",
-  "eslint": "^9",
+    "eslint": "^9",
     "eslint-config-next": "15.4.3",
     "tailwindcss": "^4",
     "typescript": "^5"

examples/redis-minimal/package.json

@@ -0,0 +1,35 @@
+interface Post {
+    id: string
+    title: string
+    content: string
+  }
+   
+  // Next.js will invalidate the cache when a
+  // request comes in, at most once every 60 seconds.
+  export const revalidate = 60
+   
+  export async function generateStaticParams() {
+    const posts: Post[] = await fetch('https://api.vercel.app/blog').then((res) =>
+      res.json()
+    )
+    return posts.map((post) => ({
+      id: String(post.id),
+    }))
+  }
+   
+  export default async function Page({
+    params,
+  }: {
+    params: Promise<{ id: string }>
+  }) {
+    const { id } = await params
+    const post: Post = await fetch(`https://api.vercel.app/blog/${id}`).then(
+      (res) => res.json()
+    )
+    return (
+      <main>
+        <h1>{post.title}</h1>
+        <p>{post.content}</p>
+      </main>
+    )
+  }

examples/redis-minimal/src/app/isr-example/blog/[id]/page.tsx

@@ -0,0 +1,37 @@
+export async function Example({
+  searchParams,
+}: {
+  searchParams: Promise<{ characterId: string }>;
+}) {
+  const characterId = (await searchParams).characterId;
+  try {
+    const characterResponse = await fetch(
+      `https://api.sampleapis.com/futurama/characters/${characterId}`,
+      {
+        next: {
+          revalidate: 86400, // 24 hours in seconds
+          tags: ["futurama"],
+        },
+      }
+    );
+    const character = await characterResponse.json();
+    const name = character.name.first;
+    return (
+      <div>
+        <h1>Name: {name}</h1>
+        <span>{new Date().toISOString()}</span>
+      </div>
+    );
+  } catch (error) {
+    console.error("Error fetching character data:", error);
+    return (
+      <div>
+        <span>An error occurred during fetch</span>
+      </div>
+    );
+  }
+}
+
+export async function Skeleton() {
+  return <div>Loading...</div>;
+}

examples/redis-minimal/src/app/ppr-example/Example.tsx

@@ -0,0 +1,19 @@
+import { Suspense } from "react";
+import { Example, Skeleton } from "./Example";
+
+export default function Page({
+  searchParams,
+}: {
+  searchParams: Promise<{ characterId: string }>;
+}) {
+  return (
+    <section>
+      <h1>This will be prerendered</h1>
+      <Suspense fallback={<Skeleton />}>
+        <Example searchParams={searchParams} />
+      </Suspense>
+    </section>
+  );
+}
+
+export const experimental_ppr = true;

examples/redis-minimal/src/app/ppr-example/page.tsx

@@ -20,6 +20,8 @@ import {
   type GetIncrementalResponseCacheContext,
   type GetIncrementalFetchCacheContext,
   IncrementalCacheValue,
+  CachedFetchValue,
+  SetIncrementalFetchCacheContext,
 } from "next/dist/server/response-cache/types";
 import { resolveRevalidateValue } from "../helpers/resolveRevalidateValue";
 
@@ -223,6 +225,54 @@ export class CacheHandler implements NextCacheHandler {
     return cacheHandlerValue;
   }
 
+  static async #writeFetch(
+    cacheKey: string,
+    data: CachedFetchValue,
+    ctx: SetIncrementalFetchCacheContext,
+  ): Promise<void> {
+    try {
+      const fetchDataPath = path.join(
+        CacheHandler.#serverDistDir,
+        "..",
+        "cache",
+        "fetch-cache",
+        cacheKey,
+      );
+
+      await fsPromises.mkdir(path.dirname(fetchDataPath), {
+        recursive: true,
+      });
+
+      await fsPromises.writeFile(
+        fetchDataPath,
+        JSON.stringify({
+          ...data,
+          tags: ctx.fetchCache ? ctx.tags : [],
+        }),
+      );
+
+      if (CacheHandler.#debug) {
+        console.info(
+          "[CacheHandler] [handler: %s] [method: %s] [key: %s] %s",
+          "file system",
+          "set",
+          cacheKey,
+          "Successfully set value.",
+        );
+      }
+    } catch (error) {
+      if (CacheHandler.#debug) {
+        console.warn(
+          "[CacheHandler] [handler: %s] [method: %s] [key: %s] %s",
+          "file system",
+          "set",
+          cacheKey,
+          `Error: ${error}`,
+        );
+      }
+    }
+  }
+
   static async #writePagesRouterPage(
     cacheKey: string,
     pageData: IncrementalCachedPageValue,
@@ -626,6 +676,15 @@ export class CacheHandler implements NextCacheHandler {
       }
     }
 
+    if (CacheHandler.#debug) {
+      console.info(
+        "[CacheHandler] [method: %s] [key: %s] %s",
+        "get",
+        cacheKey,
+        `Retrieving value ${cachedData ? "found" : "not found"}.`,
+      );
+    }
+
     return cachedData ?? null;
   }
 
@@ -707,6 +766,14 @@ export class CacheHandler implements NextCacheHandler {
         cacheHandlerValue.value as unknown as IncrementalCachedPageValue,
       );
     }
+
+    if (cacheHandlerValue.value?.kind === "FETCH") {
+      await CacheHandler.#writeFetch(
+        cacheKey,
+        cacheHandlerValue.value as unknown as CachedFetchValue,
+        ctx as SetIncrementalFetchCacheContext,
+      );
+    }
   }
 
   async revalidateTag(