feat: kv cache

examples/vercel-blog-starter/open-next.config.ts

@@ -1,12 +1,13 @@
 import type { OpenNextConfig } from "@opennextjs/aws/types/open-next";
+import cache from "@opennextjs/cloudflare/kvCache";
 
 const config: OpenNextConfig = {
   default: {
     override: {
       wrapper: "cloudflare-node",
       converter: "edge",
-      // Unused implementation
-      incrementalCache: "dummy",
+      incrementalCache: async () => cache,
+      // Unused implementations
       tagCache: "dummy",
       queue: "dummy",
     },

packages/cloudflare/env.d.ts

@@ -1,14 +1,13 @@
 declare global {
   namespace NodeJS {
     interface ProcessEnv {
-      ASSETS: Fetcher;
       __NEXT_PRIVATE_STANDALONE_CONFIG?: string;
       SKIP_NEXT_APP_BUILD?: string;
       NEXT_PRIVATE_DEBUG_CACHE?: string;
-      __OPENNEXT_KV_BINDING_NAME: string;
       OPEN_NEXT_ORIGIN: string;
       NODE_ENV?: string;
-      __OPENNEXT_PROCESSED_ENV?: string;
+      // Whether process.env has been populated (on first request).
+      __PROCESS_ENV_POPULATED?: string;
     }
   }
 }

packages/cloudflare/package.json

@@ -22,6 +22,10 @@
     ".": {
       "import": "./dist/api/index.js",
       "types": "./dist/api/index.d.ts"
+    },
+    "./*": {
+      "import": "./dist/api/*.js",
+      "types": "./dist/api/*.d.ts"
     }
   },
   "files": [

packages/cloudflare/src/api/get-cloudflare-context.ts

@@ -1,8 +1,8 @@
-import "server-only";
-
 declare global {
-  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
-  interface CloudflareEnv {}
+  interface CloudflareEnv {
+    NEXT_CACHE_WORKERS_KV?: KVNamespace;
+    ASSETS?: Fetcher;
+  }
 }
 
 export type CloudflareContext<

packages/cloudflare/src/api/kvCache.ts

@@ -0,0 +1,126 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import type { KVNamespace } from "@cloudflare/workers-types";
+import type { Extension } from "@opennextjs/aws/types/cache";
+import type { CacheValue, IncrementalCache, WithLastModified } from "@opennextjs/aws/types/overrides";
+import { IgnorableError, RecoverableError } from "@opennextjs/aws/utils/error.js";
+
+import { getCloudflareContext } from "./get-cloudflare-context.js";
+
+export const CACHE_ASSET_DIR = "cnd-cgi/_next_cache";
+
+/**
+ * Open Next cache based on cloudflare KV and Assets.
+ *
+ * Note: The class is instantiated outside of the request context.
+ * The cloudflare context and process.env are not initialzed yet
+ * when the constructor is called.
+ */
+class Cache implements IncrementalCache {
+  readonly name = "cloudflare-kv";
+  protected initialized = false;
+  protected kv: KVNamespace | undefined;
+  protected assets: Fetcher | undefined;
+
+  async get<IsFetch extends boolean = false>(
+    key: string,
+    isFetch?: IsFetch
+  ): Promise<WithLastModified<CacheValue<IsFetch>>> {
+    if (!this.initialized) {
+      await this.init();
+    }
+
+    if (!(this.kv || this.assets)) {
+      throw new IgnorableError(`No KVNamespace nor Fetcher`);
+    }
+
+    this.debug(`Get ${key}`);
+
+    try {
+      this.debug(`- From KV`);
+      const kvKey = this.getKVKey(key, isFetch ? "fetch" : "cache");
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      let value: any = await this.kv?.get(kvKey, "json");
+      if (!value && this.assets) {
+        const url = this.getAssetUrl(key);
+        const response = await this.assets.fetch(url);
+        this.debug(`- From Assets`);
+        if (response.ok) {
+          value = await response.json();
+        }
+      }
+      if (value) {
+        this.debug(`-> hit`);
+        return { value };
+      }
+    } catch {
+      throw new RecoverableError(`Failed to get cache [${key}]`);
+    }
+
+    this.debug(`-> miss`);
+    throw new RecoverableError(`Not found [${key}]`);
+  }
+
+  async set<IsFetch extends boolean = false>(
+    key: string,
+    value: CacheValue<IsFetch>,
+    isFetch?: IsFetch
+  ): Promise<void> {
+    if (!this.initialized) {
+      await this.init();
+    }
+    if (!this.kv) {
+      throw new IgnorableError(`No KVNamespace`);
+    }
+    this.debug(`Set ${key}`);
+    try {
+      const kvKey = this.getKVKey(key, isFetch ? "fetch" : "cache");
+      // TODO: add TTL to avoid cache growing too big ?
+      await this.kv.put(kvKey, JSON.stringify(value));
+    } catch {
+      throw new RecoverableError(`Failed to set cache [${key}]`);
+    }
+  }
+
+  async delete(key: string): Promise<void> {
+    if (!this.initialized) {
+      await this.init();
+    }
+    if (!this.kv) {
+      throw new IgnorableError(`No KVNamespace`);
+    }
+    this.debug(`Delete ${key}`);
+    try {
+      const kvKey = this.getKVKey(key, "cache");
+      await this.kv.delete(kvKey);
+    } catch (e) {
+      throw new RecoverableError(`Failed to delete cache [${key}]`);
+    }
+  }
+
+  protected getKVKey(key: string, extension: Extension): string {
+    return `${this.getBuildId()}/${key}.${extension}`;
+  }
+
+  protected getAssetUrl(key: string): string {
+    return `http://assets.local/${CACHE_ASSET_DIR}/${this.getBuildId()}/${key}.cache`.replace(/\/\//g, "/");
+  }
+
+  protected debug(...args: unknown[]) {
+    if (process.env.NEXT_PRIVATE_DEBUG_CACHE) {
+      console.log(`[Cache ${this.name}] `, ...args);
+    }
+  }
+
+  protected getBuildId() {
+    return process.env.NEXT_BUILD_ID ?? "no-build-id";
+  }
+
+  protected async init() {
+    const env = (await getCloudflareContext()).env;
+    this.kv = env.NEXT_CACHE_WORKERS_KV;
+    this.assets = env.ASSETS;
+    this.initialized = true;
+  }
+}
+
+export default new Cache();

packages/cloudflare/src/cli/build/bundle-server.ts

@@ -8,7 +8,6 @@ import { build, Plugin } from "esbuild";
 
 import { Config } from "../config.js";
 import * as patches from "./patches/index.js";
-import { copyPrerenderedRoutes } from "./utils/index.js";
 
 /** The dist directory of the Cloudflare adapter package */
 const packageDistDir = path.join(path.dirname(fileURLToPath(import.meta.url)), "../..");
@@ -17,9 +16,6 @@ const packageDistDir = path.join(path.dirname(fileURLToPath(import.meta.url)), "
  * Bundle the Open Next server.
  */
 export async function bundleServer(config: Config, openNextOptions: BuildOptions): Promise<void> {
-  // Copy over prerendered assets (e.g. SSG routes)
-  copyPrerenderedRoutes(config);
-
   patches.copyPackageCliFiles(packageDistDir, config, openNextOptions);
 
   const nextConfigStr =

packages/cloudflare/src/cli/build/index.ts

@@ -5,7 +5,7 @@ import { dirname, join } from "node:path";
 import { buildNextjsApp, setStandaloneBuildMode } from "@opennextjs/aws/build/buildNextApp.js";
 import { compileCache } from "@opennextjs/aws/build/compileCache.js";
 import { compileOpenNextConfig } from "@opennextjs/aws/build/compileConfig.js";
-import { createStaticAssets } from "@opennextjs/aws/build/createAssets.js";
+import { createCacheAssets, createStaticAssets } from "@opennextjs/aws/build/createAssets.js";
 import { createMiddleware } from "@opennextjs/aws/build/createMiddleware.js";
 import * as buildHelper from "@opennextjs/aws/build/helper.js";
 import { printHeader, showWarningOnWindows } from "@opennextjs/aws/build/utils.js";
@@ -16,6 +16,7 @@ import type { ProjectOptions } from "../config.js";
 import { containsDotNextDir, getConfig } from "../config.js";
 import { bundleServer } from "./bundle-server.js";
 import { compileEnvFiles } from "./open-next/compile-env-files.js";
+import { copyCacheAssets } from "./open-next/copyCacheAssets.js";
 import { createServerBundle } from "./open-next/createServerBundle.js";
 
 /**
@@ -80,6 +81,11 @@ export async function build(projectOpts: ProjectOptions): Promise<void> {
 
   createStaticAssets(options);
 
+  if (config.dangerous?.disableIncrementalCache !== true) {
+    createCacheAssets(options);
+    copyCacheAssets(options);
+  }
+
   await createServerBundle(options);
 
   // TODO: drop this copy.
@@ -103,10 +109,11 @@ function ensureCloudflareConfig(config: OpenNextConfig) {
   const requirements = {
     dftUseCloudflareWrapper: config.default?.override?.wrapper === "cloudflare-node",
     dftUseEdgeConverter: config.default?.override?.converter === "edge",
-    dftUseDummyCache:
-      config.default?.override?.incrementalCache === "dummy" &&
-      config.default?.override?.tagCache === "dummy" &&
-      config.default?.override?.queue === "dummy",
+    dftMaybeUseCache:
+      config.default?.override?.incrementalCache === "dummy" ||
+      typeof config.default?.override?.incrementalCache === "function",
+    dftUseDummyTagCache:
+      config.default?.override?.tagCache === "dummy" && config.default?.override?.queue === "dummy",
     disableCacheInterception: config.dangerous?.enableCacheInterception !== true,
     mwIsMiddlewareExternal: config.middleware?.external == true,
     mwUseCloudflareWrapper: config.middleware?.override?.wrapper === "cloudflare-edge",
@@ -121,7 +128,7 @@ function ensureCloudflareConfig(config: OpenNextConfig) {
     override: {
       wrapper: "cloudflare-node",
       converter: "edge",
-      incrementalCache: "dummy",
+      incrementalCache: "dummy" | function,
       tagCache: "dummy",
       queue: "dummy",
     },

packages/cloudflare/src/cli/build/open-next/copyCacheAssets.ts

@@ -0,0 +1,15 @@
+import { cpSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+import * as buildHelper from "@opennextjs/aws/build/helper.js";
+
+import { CACHE_ASSET_DIR } from "../../../api/kvCache.js";
+
+export function copyCacheAssets(options: buildHelper.BuildOptions) {
+  const { appBuildOutputPath, outputDir } = options;
+  const buildId = buildHelper.getBuildId(appBuildOutputPath);
+  const srcPath = join(outputDir, "cache", buildId);
+  const dstPath = join(outputDir, "assets", CACHE_ASSET_DIR, buildId);
+  mkdirSync(dstPath, { recursive: true });
+  cpSync(srcPath, dstPath, { recursive: true });
+}

packages/cloudflare/src/cli/build/utils/index.ts

@@ -1,4 +1,3 @@
-export * from "./copy-prerendered-routes.js";
 export * from "./extract-project-env-vars.js";
 export * from "./normalize-path.js";
 export * from "./ts-parse-file.js";

packages/cloudflare/src/cli/config.ts

@@ -46,10 +46,6 @@ export type Config = {
     };
   };
 
-  cache: {
-    kvBindingName: string;
-  };
-
   // Internal name for the copy of the package
   internalPackageName: string;
 };
@@ -74,8 +70,6 @@ export function getConfig(projectOpts: ProjectOptions): Config {
   const internalPackage = join(nodeModules, ...PACKAGE_NAME.split("/"));
   const internalTemplates = join(internalPackage, "cli", "templates");
 
-  process.env.__OPENNEXT_KV_BINDING_NAME ??= "NEXT_CACHE_WORKERS_KV";
-
   return {
     build: {
       timestamp: Date.now(),
@@ -104,10 +98,6 @@ export function getConfig(projectOpts: ProjectOptions): Config {
       },
     },
 
-    cache: {
-      kvBindingName: process.env.__OPENNEXT_KV_BINDING_NAME,
-    },
-
     internalPackageName: PACKAGE_NAME,
   };
 }