opennextjs · vicb · Mar 26, 2025 · Mar 25, 2025 · Mar 25, 2025 · Mar 25, 2025
diff --git a/.changeset/cyan-donuts-perform.md b/.changeset/cyan-donuts-perform.md
@@ -0,0 +1,31 @@
+---
+"@opennextjs/cloudflare": minor
+---
+
+Refactor the codebase for consistency
+
+BREAKING CHANGE
+
+Overrides:
+
+Overrides now live in `@opennextjs/cloudflare/overrides` and some files have been renamed.
+
+- Incremental cache overrides: `@opennextjs/cloudflare/overrides/incremental-cache/...`
+- Tag cache overrides: `@opennextjs/cloudflare/overrides/tag-cache/...`
+- Queue overrides: `@opennextjs/cloudflare/overrides/queue/...`
+
+For example the KV incremental cache override can be imported as `@opennextjs/cloudflare/overrides/incremental-cache/kv-incremental-cache`.
+
+Environment variables and bindings name changes:
+
+- `NEXT_CACHE_WORKERS_KV` -> `NEXT_INC_CACHE_KV`
+- `NEXT_CACHE_R2_...` -> `NEXT_INC_CACHE_R2_...`
+- `NEXT_CACHE_D1` -> `NEXT_TAG_CACHE_D1`
+- `NEXT_CACHE_DO_...` -> `NEXT_TAG_CACHE_DO_...`
+- `NEXT_CACHE_DO_REVALIDATION` -> `NEXT_CACHE_DO_QUEUE`
+- `NEXT_CACHE_REVALIDATION_WORKER` -> `WORKER_SELF_REFERENCE`
+
+Other:
+
+`NEXT_CACHE_D1_TAGS_TABLE` and `NEXT_CACHE_D1_REVALIDATIONS_TABLE` have been dropped.
+The tables have a fixed names `tags` and `revalidations`.
diff --git a/examples/e2e/app-pages-router/open-next.config.ts b/examples/e2e/app-pages-router/open-next.config.ts
@@ -1,6 +1,6 @@
 import { defineCloudflareConfig } from "@opennextjs/cloudflare";
-import kvIncrementalCache from "@opennextjs/cloudflare/kv-cache";
-import memoryQueue from "@opennextjs/cloudflare/memory-queue";
+import kvIncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/kv-incremental-cache";
+import memoryQueue from "@opennextjs/cloudflare/overrides/queue/memory-queue";
 
 export default defineCloudflareConfig({
   incrementalCache: kvIncrementalCache,

diff --git a/examples/e2e/app-pages-router/wrangler.jsonc b/examples/e2e/app-pages-router/wrangler.jsonc
@@ -10,13 +10,13 @@
   },
   "kv_namespaces": [
     {
-      "binding": "NEXT_CACHE_WORKERS_KV",
+      "binding": "NEXT_INC_CACHE_KV",
       "id": "<BINDING_ID>"
     }
   ],
   "services": [
     {
-      "binding": "NEXT_CACHE_REVALIDATION_WORKER",
+      "binding": "WORKER_SELF_REFERENCE",
       "service": "app-pages-router"
     }
   ]

diff --git a/examples/e2e/app-router/open-next.config.ts b/examples/e2e/app-router/open-next.config.ts
@@ -1,13 +1,13 @@
 import { defineCloudflareConfig } from "@opennextjs/cloudflare";
-import kvIncrementalCache from "@opennextjs/cloudflare/kv-cache";
-import shardedTagCache from "@opennextjs/cloudflare/do-sharded-tag-cache";
-import doQueue from "@opennextjs/cloudflare/durable-queue";
+import kvIncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/kv-incremental-cache";
+import shardedTagCache from "@opennextjs/cloudflare/overrides/tag-cache/do-sharded-tag-cache";
+import doQueue from "@opennextjs/cloudflare/overrides/queue/do-queue";
 
 export default defineCloudflareConfig({
   incrementalCache: kvIncrementalCache,
-  // With such a configuration, we could have up to 12 * (8 + 2) = 120 Durable Objects instances
+  // With such a configuration, we could have up to 2 * 6 * (8 + 2) = 120 Durable Objects instances
   tagCache: shardedTagCache({
-    numberOfShards: 12,
+    baseShardSize: 6,
     enableShardReplication: true,
     shardReplicationOptions: {
       numberOfSoftReplicas: 8,

diff --git a/examples/e2e/app-router/wrangler.jsonc b/examples/e2e/app-router/wrangler.jsonc
@@ -11,11 +11,11 @@
   "durable_objects": {
     "bindings": [
       {
-        "name": "NEXT_CACHE_REVALIDATION_DURABLE_OBJECT",
+        "name": "NEXT_CACHE_DO_QUEUE",
         "class_name": "DurableObjectQueueHandler"
       },
       {
-        "name": "NEXT_CACHE_DO_SHARDED",
+        "name": "NEXT_TAG_CACHE_DO_SHARDED",
         "class_name": "DOShardedTagCache"
       }
     ]
@@ -28,13 +28,13 @@
   ],
   "kv_namespaces": [
     {
-      "binding": "NEXT_CACHE_WORKERS_KV",
+      "binding": "NEXT_INC_CACHE_KV",
       "id": "<BINDING_ID>"
     }
   ],
   "services": [
     {
-      "binding": "NEXT_CACHE_REVALIDATION_WORKER",
+      "binding": "WORKER_SELF_REFERENCE",
       "service": "app-router"
     }
   ]

diff --git a/examples/e2e/pages-router/open-next.config.ts b/examples/e2e/pages-router/open-next.config.ts
@@ -1,6 +1,6 @@
 import { defineCloudflareConfig } from "@opennextjs/cloudflare";
-import kvIncrementalCache from "@opennextjs/cloudflare/kv-cache";
-import memoryQueue from "@opennextjs/cloudflare/memory-queue";
+import kvIncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/kv-incremental-cache";
+import memoryQueue from "@opennextjs/cloudflare/overrides/queue/memory-queue";
 
 export default defineCloudflareConfig({
   incrementalCache: kvIncrementalCache,

diff --git a/examples/e2e/pages-router/wrangler.jsonc b/examples/e2e/pages-router/wrangler.jsonc
@@ -10,13 +10,13 @@
   },
   "kv_namespaces": [
     {
-      "binding": "NEXT_CACHE_WORKERS_KV",
+      "binding": "NEXT_INC_CACHE_KV",
       "id": "<BINDING_ID>"
     }
   ],
   "services": [
     {
-      "binding": "NEXT_CACHE_REVALIDATION_WORKER",
+      "binding": "WORKER_SELF_REFERENCE",
       "service": "pages-router"
     }
   ]

diff --git a/examples/overrides/d1-tag-next/open-next.config.ts b/examples/overrides/d1-tag-next/open-next.config.ts
@@ -1,6 +1,6 @@
 import { defineCloudflareConfig } from "@opennextjs/cloudflare";
-import kvIncrementalCache from "@opennextjs/cloudflare/kv-cache";
-import d1NextTagCache from "@opennextjs/cloudflare/d1-next-tag-cache";
+import kvIncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/kv-incremental-cache";
+import d1NextTagCache from "@opennextjs/cloudflare/overrides/tag-cache/d1-next-tag-cache";
 
 export default defineCloudflareConfig({
   incrementalCache: kvIncrementalCache,

diff --git a/examples/overrides/d1-tag-next/wrangler.jsonc b/examples/overrides/d1-tag-next/wrangler.jsonc
@@ -13,15 +13,15 @@
   },
   "kv_namespaces": [
     {
-      "binding": "NEXT_CACHE_WORKERS_KV",
+      "binding": "NEXT_INC_CACHE_KV",
       "id": "<BINDING_ID>"
     }
   ],
   "d1_databases": [
     {
-      "binding": "NEXT_CACHE_D1",
-      "database_id": "NEXT_CACHE_D1",
-      "database_name": "NEXT_CACHE_D1"
+      "binding": "NEXT_TAG_CACHE_D1",
+      "database_id": "NEXT_TAG_CACHE_D1",
+      "database_name": "NEXT_TAG_CACHE_D1"
     }
   ]
 }
diff --git a/examples/overrides/memory-queue/open-next.config.ts b/examples/overrides/memory-queue/open-next.config.ts
@@ -1,6 +1,6 @@
 import { defineCloudflareConfig } from "@opennextjs/cloudflare";
-import kvIncrementalCache from "@opennextjs/cloudflare/kv-cache";
-import memoryQueue from "@opennextjs/cloudflare/memory-queue";
+import kvIncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/kv-incremental-cache";
+import memoryQueue from "@opennextjs/cloudflare/overrides/queue/memory-queue";
 
 export default defineCloudflareConfig({
   incrementalCache: kvIncrementalCache,

diff --git a/examples/overrides/memory-queue/wrangler.jsonc b/examples/overrides/memory-queue/wrangler.jsonc
@@ -10,13 +10,13 @@
   },
   "kv_namespaces": [
     {
-      "binding": "NEXT_CACHE_WORKERS_KV",
+      "binding": "NEXT_INC_CACHE_KV",
       "id": "<BINDING_ID>"
     }
   ],
   "services": [
     {
-      "binding": "NEXT_CACHE_REVALIDATION_WORKER",
+      "binding": "WORKER_SELF_REFERENCE",
       "service": "memory-queue"
     }
   ]

diff --git a/examples/overrides/r2-incremental-cache/open-next.config.ts b/examples/overrides/r2-incremental-cache/open-next.config.ts
@@ -1,8 +1,8 @@
 import { defineCloudflareConfig } from "@opennextjs/cloudflare";
-import d1TagCache from "@opennextjs/cloudflare/d1-tag-cache";
-import memoryQueue from "@opennextjs/cloudflare/memory-queue";
-import r2IncrementalCache from "@opennextjs/cloudflare/r2-incremental-cache";
-import { withRegionalCache } from "@opennextjs/cloudflare/regional-cache";
+import d1TagCache from "@opennextjs/cloudflare/overrides/tag-cache/d1-tag-cache";
+import memoryQueue from "@opennextjs/cloudflare/overrides/queue/memory-queue";
+import r2IncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/r2-incremental-cache";
+import { withRegionalCache } from "@opennextjs/cloudflare/overrides/incremental-cache/regional-cache";
 
 export default defineCloudflareConfig({
   incrementalCache: withRegionalCache(r2IncrementalCache, {

diff --git a/examples/overrides/r2-incremental-cache/wrangler.jsonc b/examples/overrides/r2-incremental-cache/wrangler.jsonc
@@ -12,22 +12,22 @@
     "e2e": {
       "d1_databases": [
         {
-          "binding": "NEXT_CACHE_D1",
-          "database_id": "NEXT_CACHE_D1",
-          "database_name": "NEXT_CACHE_D1"
+          "binding": "NEXT_TAG_CACHE_D1",
+          "database_id": "NEXT_TAG_CACHE_D1",
+          "database_name": "NEXT_TAG_CACHE_D1"
         }
       ],
       "services": [
         {
-          "binding": "NEXT_CACHE_REVALIDATION_WORKER",
+          "binding": "WORKER_SELF_REFERENCE",
           "service": "r2-incremental-cache-e2e"
         }
       ],
       "r2_buckets": [
         {
-          "binding": "NEXT_CACHE_R2_BUCKET",
-          "bucket_name": "NEXT_CACHE_R2_BUCKET",
-          "preview_bucket_name": "NEXT_CACHE_R2_BUCKET"
+          "binding": "NEXT_INC_CACHE_R2_BUCKET",
+          "bucket_name": "NEXT_INC_CACHE_R2_BUCKET",
+          "preview_bucket_name": "NEXT_INC_CACHE_R2_BUCKET"
         }
       ]
     },

diff --git a/examples/playground14/open-next.config.ts b/examples/playground14/open-next.config.ts
@@ -1,5 +1,5 @@
 import { defineCloudflareConfig } from "@opennextjs/cloudflare";
-import kvIncrementalCache from "@opennextjs/cloudflare/kv-cache";
+import kvIncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/kv-incremental-cache";
 
 export default defineCloudflareConfig({
   incrementalCache: kvIncrementalCache,

diff --git a/examples/playground14/wrangler.jsonc b/examples/playground14/wrangler.jsonc
@@ -10,7 +10,7 @@
   },
   "kv_namespaces": [
     {
-      "binding": "NEXT_CACHE_WORKERS_KV",
+      "binding": "NEXT_INC_CACHE_KV",
       "id": "<BINDING_ID>"
     }
   ],

diff --git a/examples/playground15/open-next.config.ts b/examples/playground15/open-next.config.ts
@@ -1,5 +1,5 @@
 import { defineCloudflareConfig } from "@opennextjs/cloudflare";
-import kvIncrementalCache from "@opennextjs/cloudflare/kv-cache";
+import kvIncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/kv-incremental-cache";
 
 export default defineCloudflareConfig({
   incrementalCache: kvIncrementalCache,

diff --git a/examples/playground15/wrangler.jsonc b/examples/playground15/wrangler.jsonc
@@ -10,7 +10,7 @@
   },
   "kv_namespaces": [
     {
-      "binding": "NEXT_CACHE_WORKERS_KV",
+      "binding": "NEXT_INC_CACHE_KV",
       "id": "<BINDING_ID>"
     }
   ],

diff --git a/examples/ssg-app/open-next.config.ts b/examples/ssg-app/open-next.config.ts
@@ -1,5 +1,5 @@
 import { defineCloudflareConfig } from "@opennextjs/cloudflare";
-import kvIncrementalCache from "@opennextjs/cloudflare/kv-cache";
+import kvIncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/kv-incremental-cache";
 
 export default defineCloudflareConfig({
   incrementalCache: kvIncrementalCache,

diff --git a/examples/vercel-blog-starter/open-next.config.ts b/examples/vercel-blog-starter/open-next.config.ts
@@ -1,5 +1,5 @@
 import { defineCloudflareConfig } from "@opennextjs/cloudflare";
-import kvIncrementalCache from "@opennextjs/cloudflare/kv-cache";
+import kvIncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/kv-incremental-cache";
 
 export default defineCloudflareConfig({
   incrementalCache: kvIncrementalCache,

diff --git a/packages/cloudflare/env.d.ts b/packages/cloudflare/env.d.ts
@@ -7,8 +7,6 @@ declare global {
       NEXT_PRIVATE_DEBUG_CACHE?: string;
       OPEN_NEXT_ORIGIN: string;
       NODE_ENV?: string;
-      NEXT_CACHE_D1_TAGS_TABLE?: string;
-      NEXT_CACHE_D1_REVALIDATIONS_TABLE?: string;
     }
   }
 }

diff --git a/packages/cloudflare/src/api/cloudflare-context.ts b/packages/cloudflare/src/api/cloudflare-context.ts
@@ -12,42 +12,42 @@ declare global {
     // Default to "production"
     NEXTJS_ENV?: string;
 
-    // KV used for the incremental cache
-    NEXT_CACHE_WORKERS_KV?: KVNamespace;
-    // D1 db used for the tag cache
-    NEXT_CACHE_D1?: D1Database;
-    // D1 table to use for the tag cache for the tag/path mapping
-    NEXT_CACHE_D1_TAGS_TABLE?: string;
-    // D1 table to use for the tag cache for storing the tag and their associated revalidation times
-    NEXT_CACHE_D1_REVALIDATIONS_TABLE?: string;
     // Service binding for the worker itself to be able to call itself from within the worker
-    NEXT_CACHE_REVALIDATION_WORKER?: Service;
+    WORKER_SELF_REFERENCE?: Service;
+
+    // KV used for the incremental cache
+    NEXT_INC_CACHE_KV?: KVNamespace;
+
     // R2 bucket used for the incremental cache
-    NEXT_CACHE_R2_BUCKET?: R2Bucket;
+    NEXT_INC_CACHE_R2_BUCKET?: R2Bucket;
     // Prefix used for the R2 incremental cache bucket
-    NEXT_CACHE_R2_PREFIX?: string;
-    // Durable Object namespace to use for the durable object queue handler
-    NEXT_CACHE_REVALIDATION_DURABLE_OBJECT?: DurableObjectNamespace<DurableObjectQueueHandler>;
+    NEXT_INC_CACHE_R2_PREFIX?: string;
+
+    // D1 db used for the tag cache
+    NEXT_TAG_CACHE_D1?: D1Database;
+
     // Durables object namespace to use for the sharded tag cache
-    NEXT_CACHE_DO_SHARDED?: DurableObjectNamespace<DOShardedTagCache>;
+    NEXT_TAG_CACHE_DO_SHARDED?: DurableObjectNamespace<DOShardedTagCache>;
     // Queue of failed tag write
-    // It could be used for monitoring or to reprocess failed writes
-    // Entirely optional
-    NEXT_CACHE_DO_SHARDED_DLQ?: Queue;
+    // Optional, could be used to monitor or reprocess failed writes
+    NEXT_TAG_CACHE_DO_SHARDED_DLQ?: Queue;
+
+    // Durable Object namespace to use for the durable object queue
+    NEXT_CACHE_DO_QUEUE?: DurableObjectNamespace<DurableObjectQueueHandler>;
 
-    // Below are the potential environment variables that can be set by the user to configure the durable object queue handler
+    // Below are the environment variables to configure the durable object queue
     // The max number of revalidations that can be processed by the durable worker at the same time
-    MAX_REVALIDATION_BY_DURABLE_OBJECT?: string;
+    NEXT_CACHE_DO_QUEUE_MAX_REVALIDATION?: string;
     // The max time in milliseconds that a revalidation can take before being considered as failed
-    REVALIDATION_TIMEOUT_MS?: string;
+    NEXT_CACHE_DO_QUEUE_REVALIDATION_TIMEOUT_MS?: string;
     // The amount of time after which a revalidation will be attempted again if it failed
     // If it fails again it will exponentially back off until it reaches the max retry interval
-    REVALIDATION_RETRY_INTERVAL_MS?: string;
+    NEXT_CACHE_DO_QUEUE_RETRY_INTERVAL_MS?: string;
     // The maximum number of attempts that can be made to revalidate a path
-    MAX_REVALIDATION_ATTEMPTS?: string;
+    NEXT_CACHE_DO_QUEUE_MAX_NUM_REVALIDATIONS?: string;
     // Disable SQLite for the durable object queue handler
     // This can be safely used if you don't use an eventually consistent incremental cache (i.e. R2 without the regional cache for example)
-    REVALIDATION_DO_DISABLE_SQLITE?: string;
+    NEXT_CACHE_DO_QUEUE_DISABLE_SQLITE?: string;
   }
 }
 

diff --git a/packages/cloudflare/src/api/constants.ts b/packages/cloudflare/src/api/constants.ts
diff --git a/packages/cloudflare/src/api/durable-objects/queue.spec.ts b/packages/cloudflare/src/api/durable-objects/queue.spec.ts
@@ -37,7 +37,7 @@ const createDurableObjectQueue = ({
   };
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   return new DurableObjectQueueHandler(mockState as any, {
-    NEXT_CACHE_REVALIDATION_WORKER: {
+    WORKER_SELF_REFERENCE: {
       fetch: vi.fn().mockReturnValue(
         new Promise<Response>((res) =>
           setTimeout(
@@ -54,7 +54,7 @@ const createDurableObjectQueue = ({
       ),
       connect: vi.fn(),
     },
-    REVALIDATION_DO_DISABLE_SQLITE: disableSQLite ? "true" : undefined,
+    NEXT_CACHE_DO_QUEUE_DISABLE_SQLITE: disableSQLite ? "true" : undefined,
   });
 };