feat: replace NEXT_BUILD_ID with OPEN_NEXT_BUILD_ID

edmundhung · edmundhung · commit 196a2058e98c · 2026-04-17T17:38:51.000+01:00
diff --git a/.changeset/funny-toes-exist.md b/.changeset/funny-toes-exist.md
@@ -0,0 +1,5 @@
+---
+"@opennextjs/cloudflare": patch
+---
+
+Prefer `OPEN_NEXT_BUILD_ID` for Cloudflare cache keys, populating it from Next `deploymentId` with the build ID as a fallback.
diff --git a/packages/cloudflare/src/api/overrides/incremental-cache/kv-incremental-cache.ts b/packages/cloudflare/src/api/overrides/incremental-cache/kv-incremental-cache.ts
@@ -102,7 +102,7 @@ class KVIncrementalCache implements IncrementalCache {
 	protected getKVKey(key: string, cacheType?: CacheEntryType): string {
 		return computeCacheKey(key, {
 			prefix: getCloudflareContext().env[PREFIX_ENV_NAME],
-			buildId: process.env.NEXT_BUILD_ID,
+			buildId: process.env.OPEN_NEXT_BUILD_ID,
 			cacheType,
 		});
 	}
diff --git a/packages/cloudflare/src/api/overrides/incremental-cache/r2-incremental-cache.ts b/packages/cloudflare/src/api/overrides/incremental-cache/r2-incremental-cache.ts
@@ -82,7 +82,7 @@ class R2IncrementalCache implements IncrementalCache {
 	protected getR2Key(key: string, cacheType?: CacheEntryType): string {
 		return computeCacheKey(key, {
 			prefix: getCloudflareContext().env[PREFIX_ENV_NAME],
-			buildId: process.env.NEXT_BUILD_ID,
+			buildId: process.env.OPEN_NEXT_BUILD_ID,
 			cacheType,
 		});
 	}
diff --git a/packages/cloudflare/src/api/overrides/incremental-cache/regional-cache.ts b/packages/cloudflare/src/api/overrides/incremental-cache/regional-cache.ts
@@ -190,7 +190,7 @@ class RegionalCache implements IncrementalCache {
 	}
 
 	protected getCacheUrlKey(key: string, cacheType?: CacheEntryType) {
-		const buildId = process.env.NEXT_BUILD_ID ?? FALLBACK_BUILD_ID;
+		const buildId = process.env.OPEN_NEXT_BUILD_ID ?? FALLBACK_BUILD_ID;
 		return "http://cache.local" + `/${buildId}/${key}`.replace(/\/+/g, "/") + `.${cacheType ?? "cache"}`;
 	}
 
diff --git a/packages/cloudflare/src/api/overrides/incremental-cache/static-assets-incremental-cache.ts b/packages/cloudflare/src/api/overrides/incremental-cache/static-assets-incremental-cache.ts
@@ -65,7 +65,7 @@ class StaticAssetsIncrementalCache implements IncrementalCache {
 		if (cacheType === "composable") {
 			throw new Error("Composable cache is not supported in static assets incremental cache");
 		}
-		const buildId = process.env.NEXT_BUILD_ID ?? FALLBACK_BUILD_ID;
+		const buildId = process.env.OPEN_NEXT_BUILD_ID ?? FALLBACK_BUILD_ID;
 		const name = (
 			cacheType === "fetch"
 				? `${CACHE_DIR}/__fetch/${buildId}/${key}`
diff --git a/packages/cloudflare/src/api/overrides/tag-cache/d1-next-tag-cache.spec.ts b/packages/cloudflare/src/api/overrides/tag-cache/d1-next-tag-cache.spec.ts
@@ -143,9 +143,10 @@ describe("D1NextModeTagCache", () => {
 			expect(error).toHaveBeenCalledWith(mockError);
 		});
 
-		it("should use custom build ID when NEXT_BUILD_ID is set", async () => {
+		it("should prefer OPEN_NEXT_BUILD_ID when it is set", async () => {
 			const customBuildId = "custom-build-id";
-			vi.stubEnv("NEXT_BUILD_ID", customBuildId);
+			vi.stubEnv("NEXT_BUILD_ID", "legacy-build-id");
+			vi.stubEnv("OPEN_NEXT_BUILD_ID", customBuildId);
 
 			mockRaw.mockResolvedValue([[`${customBuildId}/tag1`, 123, 123, null]]);
 
@@ -534,9 +535,9 @@ describe("D1NextModeTagCache", () => {
 			expect(cacheKey).toBe(`${FALLBACK_BUILD_ID}/${key}`);
 		});
 
-		it("should use custom build ID when NEXT_BUILD_ID is set", () => {
+		it("should use custom build ID when OPEN_NEXT_BUILD_ID is set", () => {
 			const customBuildId = "custom-build-id";
-			vi.stubEnv("NEXT_BUILD_ID", customBuildId);
+			vi.stubEnv("OPEN_NEXT_BUILD_ID", customBuildId);
 
 			const key = "test-tag";
 			const cacheKey = (tagCache as unknown as { getCacheKey: (key: string) => string }).getCacheKey(key);
@@ -545,7 +546,7 @@ describe("D1NextModeTagCache", () => {
 		});
 
 		it("should handle double slashes by replacing them with single slash", () => {
-			vi.stubEnv("NEXT_BUILD_ID", "build//id");
+			vi.stubEnv("OPEN_NEXT_BUILD_ID", "build//id");
 
 			const key = "test-tag";
 			const cacheKey = (tagCache as unknown as { getCacheKey: (key: string) => string }).getCacheKey(key);
@@ -555,16 +556,16 @@ describe("D1NextModeTagCache", () => {
 	});
 
 	describe("getBuildId", () => {
-		it("should return NEXT_BUILD_ID when set", () => {
+		it("should return OPEN_NEXT_BUILD_ID when set", () => {
 			const customBuildId = "custom-build-id";
-			vi.stubEnv("NEXT_BUILD_ID", customBuildId);
+			vi.stubEnv("OPEN_NEXT_BUILD_ID", customBuildId);
 
 			const buildId = (tagCache as unknown as { getBuildId: () => string }).getBuildId();
 
 			expect(buildId).toBe(customBuildId);
 		});
 
-		it("should return fallback build ID when NEXT_BUILD_ID is not set", () => {
+		it("should return fallback build ID when no build ID env vars are set", () => {
 			const buildId = (tagCache as unknown as { getBuildId: () => string }).getBuildId();
 
 			expect(buildId).toBe(FALLBACK_BUILD_ID);
diff --git a/packages/cloudflare/src/api/overrides/tag-cache/d1-next-tag-cache.ts b/packages/cloudflare/src/api/overrides/tag-cache/d1-next-tag-cache.ts
@@ -190,7 +190,7 @@ export class D1NextModeTagCache implements NextModeTagCache {
 	}
 
 	protected getBuildId() {
-		return process.env.NEXT_BUILD_ID ?? FALLBACK_BUILD_ID;
+		return process.env.OPEN_NEXT_BUILD_ID ?? FALLBACK_BUILD_ID;
 	}
 
 	/**
diff --git a/packages/cloudflare/src/api/overrides/tag-cache/kv-next-tag-cache.spec.ts b/packages/cloudflare/src/api/overrides/tag-cache/kv-next-tag-cache.spec.ts
@@ -126,9 +126,10 @@ describe("KVNextModeTagCache", () => {
 			expect(error).toHaveBeenCalledWith(mockError);
 		});
 
-		it("should use custom build ID when NEXT_BUILD_ID is set", async () => {
+		it("should prefer OPEN_NEXT_BUILD_ID when it is set", async () => {
 			const customBuildId = "custom-build-id";
-			vi.stubEnv("NEXT_BUILD_ID", customBuildId);
+			vi.stubEnv("NEXT_BUILD_ID", "legacy-build-id");
+			vi.stubEnv("OPEN_NEXT_BUILD_ID", customBuildId);
 
 			mockGet.mockResolvedValue(new Map([["tag1", null]]));
 
@@ -393,9 +394,9 @@ describe("KVNextModeTagCache", () => {
 			expect(cacheKey).toBe(`${FALLBACK_BUILD_ID}/${key}`);
 		});
 
-		it("should use custom build ID when NEXT_BUILD_ID is set", () => {
+		it("should use custom build ID when OPEN_NEXT_BUILD_ID is set", () => {
 			const customBuildId = "custom-build-id";
-			vi.stubEnv("NEXT_BUILD_ID", customBuildId);
+			vi.stubEnv("OPEN_NEXT_BUILD_ID", customBuildId);
 
 			const key = "test-tag";
 			const cacheKey = (tagCache as unknown as { getCacheKey: (key: string) => string }).getCacheKey(key);
@@ -404,7 +405,7 @@ describe("KVNextModeTagCache", () => {
 		});
 
 		it("should handle double slashes by replacing them with single slash", () => {
-			vi.stubEnv("NEXT_BUILD_ID", "build//id");
+			vi.stubEnv("OPEN_NEXT_BUILD_ID", "build//id");
 
 			const key = "test-tag";
 			const cacheKey = (tagCache as unknown as { getCacheKey: (key: string) => string }).getCacheKey(key);
@@ -414,18 +415,16 @@ describe("KVNextModeTagCache", () => {
 	});
 
 	describe("getBuildId", () => {
-		it("should return NEXT_BUILD_ID when set", () => {
+		it("should return OPEN_NEXT_BUILD_ID when set", () => {
 			const customBuildId = "custom-build-id";
-			vi.stubEnv("NEXT_BUILD_ID", customBuildId);
+			vi.stubEnv("OPEN_NEXT_BUILD_ID", customBuildId);
 
 			const buildId = (tagCache as unknown as { getBuildId: () => string }).getBuildId();
 
 			expect(buildId).toBe(customBuildId);
 		});
 
-		it("should return fallback build ID when NEXT_BUILD_ID is not set", () => {
-			// Environment variables are cleared by vi.unstubAllEnvs() in beforeEach
-
+		it("should return fallback build ID when no build ID env vars are set", () => {
 			const buildId = (tagCache as unknown as { getBuildId: () => string }).getBuildId();
 
 			expect(buildId).toBe(FALLBACK_BUILD_ID);
diff --git a/packages/cloudflare/src/api/overrides/tag-cache/kv-next-tag-cache.ts b/packages/cloudflare/src/api/overrides/tag-cache/kv-next-tag-cache.ts
@@ -216,7 +216,7 @@ export class KVNextModeTagCache implements NextModeTagCache {
 	}
 
 	protected getBuildId() {
-		return process.env.NEXT_BUILD_ID ?? FALLBACK_BUILD_ID;
+		return process.env.OPEN_NEXT_BUILD_ID ?? FALLBACK_BUILD_ID;
 	}
 
 	/**
diff --git a/packages/cloudflare/src/cli/build/open-next/compile-init.ts b/packages/cloudflare/src/cli/build/open-next/compile-init.ts
@@ -1,7 +1,7 @@
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { loadConfig } from "@opennextjs/aws/adapters/config/util.js";
+import { loadBuildId, loadConfig } from "@opennextjs/aws/adapters/config/util.js";
 import type { BuildOptions } from "@opennextjs/aws/build/helper.js";
 import { build } from "esbuild";
 import type { Unstable_Config } from "wrangler";
@@ -13,10 +13,12 @@ export async function compileInit(options: BuildOptions, wranglerConfig: Unstabl
 	const currentDir = path.join(path.dirname(fileURLToPath(import.meta.url)));
 	const templatesDir = path.join(currentDir, "../../templates");
 	const initPath = path.join(templatesDir, "init.js");
+	const dotNextDir = path.join(options.appBuildOutputPath, ".next");
 
-	const nextConfig = loadConfig(path.join(options.appBuildOutputPath, ".next"));
+	const nextConfig = loadConfig(dotNextDir);
 	const basePath = nextConfig.basePath ?? "";
 	const deploymentId = nextConfig.deploymentId ?? "";
+	const openNextBuildId = nextConfig.deploymentId ?? loadBuildId(dotNextDir);
 	const trailingSlash = nextConfig.trailingSlash ?? false;
 
 	await build({
@@ -32,6 +34,7 @@ export async function compileInit(options: BuildOptions, wranglerConfig: Unstabl
 			__NEXT_BASE_PATH__: JSON.stringify(basePath),
 			__ASSETS_RUN_WORKER_FIRST__: JSON.stringify(wranglerConfig.assets?.run_worker_first ?? false),
 			__DEPLOYMENT_ID__: JSON.stringify(deploymentId),
+			__OPEN_NEXT_BUILD_ID__: JSON.stringify(openNextBuildId),
 			__TRAILING_SLASH__: JSON.stringify(trailingSlash),
 		},
 	});
diff --git a/packages/cloudflare/src/cli/templates/init.ts b/packages/cloudflare/src/cli/templates/init.ts
@@ -145,6 +145,7 @@ function populateProcessEnv(url: URL, env: CloudflareEnv) {
 	if (__DEPLOYMENT_ID__) {
 		process.env.DEPLOYMENT_ID = __DEPLOYMENT_ID__;
 	}
+	process.env.OPEN_NEXT_BUILD_ID = __OPEN_NEXT_BUILD_ID__;
 }
 
 declare global {
@@ -156,6 +157,8 @@ declare global {
 	var __ASSETS_RUN_WORKER_FIRST__: boolean | string[] | undefined;
 	// Deployment ID
 	var __DEPLOYMENT_ID__: string;
+	// Open Next build ID (deploymentId or fallback buildId)
+	var __OPEN_NEXT_BUILD_ID__: string;
 	// Next trailingSlash config
 	var __TRAILING_SLASH__: boolean;
 }

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@opennextjs/cloudflare": patch
 +---
++
 +Prefer `OPEN_NEXT_BUILD_ID` for Cloudflare cache keys, populating it from Next `deploymentId` with the build ID as a fallback.
Original file line number	Diff line number	Diff line change
`@@ -102,7 +102,7 @@ class KVIncrementalCache implements IncrementalCache {`
`102`	`102`	`protected getKVKey(key: string, cacheType?: CacheEntryType): string {`
`103`	`103`	`return computeCacheKey(key, {`
`104`	`104`	`prefix: getCloudflareContext().env[PREFIX_ENV_NAME],`
`105`		`- buildId: process.env.NEXT_BUILD_ID,`
	`105`	`+ buildId: process.env.OPEN_NEXT_BUILD_ID,`
`106`	`106`	`cacheType,`
`107`	`107`	`});`
`108`	`108`	`}`
Original file line number	Diff line number	Diff line change
`@@ -82,7 +82,7 @@ class R2IncrementalCache implements IncrementalCache {`
`82`	`82`	`protected getR2Key(key: string, cacheType?: CacheEntryType): string {`
`83`	`83`	`return computeCacheKey(key, {`
`84`	`84`	`prefix: getCloudflareContext().env[PREFIX_ENV_NAME],`
`85`		`- buildId: process.env.NEXT_BUILD_ID,`
	`85`	`+ buildId: process.env.OPEN_NEXT_BUILD_ID,`
`86`	`86`	`cacheType,`
`87`	`87`	`});`
`88`	`88`	`}`
Original file line number	Diff line number	Diff line change
`@@ -190,7 +190,7 @@ class RegionalCache implements IncrementalCache {`
`190`	`190`	`}`
`191`	`191`
`192`	`192`	`protected getCacheUrlKey(key: string, cacheType?: CacheEntryType) {`
`193`		`- const buildId = process.env.NEXT_BUILD_ID ?? FALLBACK_BUILD_ID;`
	`193`	`+ const buildId = process.env.OPEN_NEXT_BUILD_ID ?? FALLBACK_BUILD_ID;`
`194`	`194`	return "http://cache.local" + `/${buildId}/${key}`.replace(/\/+/g, "/") + `.${cacheType ?? "cache"}`;
`195`	`195`	`}`
`196`	`196`
Original file line number	Diff line number	Diff line change
`@@ -65,7 +65,7 @@ class StaticAssetsIncrementalCache implements IncrementalCache {`
`65`	`65`	`if (cacheType === "composable") {`
`66`	`66`	`throw new Error("Composable cache is not supported in static assets incremental cache");`
`67`	`67`	`}`
`68`		`- const buildId = process.env.NEXT_BUILD_ID ?? FALLBACK_BUILD_ID;`
	`68`	`+ const buildId = process.env.OPEN_NEXT_BUILD_ID ?? FALLBACK_BUILD_ID;`
`69`	`69`	`const name = (`
`70`	`70`	`cacheType === "fetch"`
`71`	`71`	? `${CACHE_DIR}/__fetch/${buildId}/${key}`
Original file line number	Diff line number	Diff line change
`@@ -190,7 +190,7 @@ export class D1NextModeTagCache implements NextModeTagCache {`
`190`	`190`	`}`
`191`	`191`
`192`	`192`	`protected getBuildId() {`
`193`		`- return process.env.NEXT_BUILD_ID ?? FALLBACK_BUILD_ID;`
	`193`	`+ return process.env.OPEN_NEXT_BUILD_ID ?? FALLBACK_BUILD_ID;`
`194`	`194`	`}`
`195`	`195`
`196`	`196`	`/**`
Original file line number	Diff line number	Diff line change
`@@ -216,7 +216,7 @@ export class KVNextModeTagCache implements NextModeTagCache {`
`216`	`216`	`}`
`217`	`217`
`218`	`218`	`protected getBuildId() {`
`219`		`- return process.env.NEXT_BUILD_ID ?? FALLBACK_BUILD_ID;`
	`219`	`+ return process.env.OPEN_NEXT_BUILD_ID ?? FALLBACK_BUILD_ID;`
`220`	`220`	`}`
`221`	`221`
`222`	`222`	`/**`