Merge branch 'main' into pr/314systems/1216

Author: vicb

.editorconfig

@@ -4,3 +4,7 @@ root = true
 [*]
 indent_style = tab
 end_of_line = lf
+
+[*.{yml,yaml}]
+indent_style = space
+indent_size = 2

AGENTS.md

@@ -0,0 +1,82 @@
+# What this is
+
+`@opennextjs/cloudflare` is an adapter that takes a Next.js `standalone` build and runs it on Cloudflare Workers via the Node.js compatibility layer. It sits on top of `@opennextjs/aws`, which provides the generic OpenNext build/runtime core; this package plugs Cloudflare-specific bindings (KV, R2, D1, Durable Objects, Assets, Images) into the override points that `@opennextjs/aws` exposes, and also contains the esbuild plugins and AST grep patches needed to rewrite Next's emitted code to run on Workers.
+
+# Layout
+
+```
+packages/cloudflare/        # the adapter
+  src/api/                  # runtime surface users import (small)
+  src/cli/                  # the `opennextjs-cloudflare` build CLI
+    commands/               # build, deploy, preview, etc. commands live here
+    build/patches/          # esbuild plugins + ast-grep patches applied to Next's output
+  templates/                # starter configs copied by `migrate` command
+examples/                   # sample Next apps used for manual + e2e testing
+create-cloudflare/          # templates for the `create-cloudflare` CLI
+benchmarking/               # perf harness
+```
+
+Two things to keep separate in your head: **`src/api`** is the tiny surface users import at runtime; **`src/cli`** is the much larger build tool. Changes to `src/api` are user-visible; changes in `src/cli/build/patches` are user-invisible but the riskiest code in the repo.
+
+# Commands
+
+Use pnpm. Run from the repo root.
+
+| Command                                | What it does                                                                                             |
+| -------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `pnpm install`                         | also triggers a `postinstall` build of the adapter.                                                      |
+| `pnpm build`                           | build `packages/cloudflare`.                                                                             |
+| `pnpm --filter cloudflare build:watch` | rebuild on change.                                                                                       |
+| `pnpm test`                            | builds, then runs all vitest suites.                                                                     |
+| `pnpm code:checks`                     | prettier + eslint + tsc.                                                                                 |
+| `pnpm fix`                             | auto-fix prettier + eslint.                                                                              |
+| `pnpm --filter <example> preview`      | build + preview an example app end-to-end. Add `SKIP_NEXT_APP_BUILD=true` when only the adapter changed. |
+| `pnpm e2e` / `pnpm e2e:dev`            | Playwright suites against the example apps.                                                              |
+| `pnpm --filter <example> e2e`          | Run a specific example's Playwright suite.                                                               |
+| `pnpm changeset`                       | create a changeset for changes.                                                                          |
+
+# Conventions
+
+- **Strict TypeScript**. Don't loosen; reach for generics or narrowing.
+- **ESM only**. Internal imports use the `.js` extension (`./foo.js`) even though the source is `.ts` - this is required for bundling, not a mistake.
+- **Unit tests are `*.spec.ts` colocated with source**, run with Vitest. Use `mock-fs` for filesystem-heavy tests. E2E coverage lives in `examples/` and runs under Playwright.
+- **Formatting is prettier**. Don't fight it; `pnpm fix`.
+- **Imports are sorted by `simple-import-sort`.** Let eslint reorder them.
+- **Dependency versions live in `pnpm-workspace.yaml` under `catalog:`.** When adding a shared dep, add it to the catalog and reference it as `"catalog:"` in the package.json. Don't pin versions inline when a catalog entry already exists.
+- **`packages/cloudflare` ships to users**. Be deliberate about adding runtime `dependencies`. Prefer `devDependencies`, inlining small helpers, or moving logic into code that only runs in the CLI.
+- **`CloudflareEnv` is augmented globally** in `src/api/cloudflare-context.ts`. New bindings that users configure should be declared there with a comment explaining what they're for.
+- **User-facing logs** go through `@opennextjs/aws`'s logger, not `console.*`. Warn (don't throw) when experimental features are used.
+
+## Where things tend to go wrong
+
+- **`src/cli/build/patches/`** contains esbuild plugins and `@ast-grep/napi` transforms that rewrite Next's emitted code to run on Workers. Every patch needs a spec, and ideally a minimal fixture of the input it's matching. Upstream Next changes break these; when a patch stops matching, fix the matcher, don't widen it blindly.
+- **Overrides in `src/api/overrides/`** implement contracts defined in `@opennextjs/aws`. Check the upstream type before changing a signature. `@opennextjs/aws` is pinned in `package.json`, so bumping it is a deliberate change with its own changeset.
+
+# Pre-PR checklist
+
+1. `pnpm code:checks` is clean.
+2. `pnpm test` passes.
+3. Changeset included if necessary.
+
+## Changesets
+
+Any behavioural change to `packages/cloudflare` needs one. Skip for internal refactors, test-only changes, example/doc tweaks.
+
+```sh
+pnpm changeset
+```
+
+Format:
+
+```
+<type>: <imperative title>
+
+<body explaining the why>
+```
+
+- `type` is one of `feature | fix | refactor | docs | chore`.
+- Bugfixes and experimental work -> `patch`.
+- New feature -> `minor`.
+- Breaking changes -> `major`.
+
+Full rules in [CONTRIBUTING.md](CONTRIBUTING.md).

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

examples/e2e/app-router/e2e/revalidateTag.test.ts

@@ -105,7 +105,7 @@ test("Revalidate tag - stale data served first", async ({ page, request }) => {
 	const staleResponse = await responsePromise;
 	const staleHeaders = staleResponse.headers();
 	const staleCache = staleHeaders["x-nextjs-cache"] ?? staleHeaders["x-opennext-cache"];
-	expect(staleCache).toMatch(/^(STALE|HIT)$/);
+	expect(staleCache).toMatch(/^(STALE)$/);
 
 	const staleTime = await page.getByTestId("cached-time").textContent();
 	// Stale content must match the pre-revalidation value
@@ -129,6 +129,19 @@ test("Revalidate tag - stale data served first", async ({ page, request }) => {
 	// After background regen the cached value must have been updated
 	expect(freshTime).not.toBeNull();
 	expect(freshTime).not.toEqual(originalTime);
+
+	// Now we want to verfiy that the next entries stays fresh (HIT) after the first stale entry
+	responsePromise = page.waitForResponse(
+		(response) => response.url().includes("/revalidate-tag/stale") && response.status() === 200
+	);
+	await page.goto("/revalidate-tag/stale");
+	const finalResponse = await responsePromise;
+	const finalHeaders = finalResponse.headers();
+	const finalCache = finalHeaders["x-nextjs-cache"] ?? finalHeaders["x-opennext-cache"];
+	expect(finalCache).toEqual("HIT");
+
+	const finalTime = await page.getByTestId("cached-time").textContent();
+	expect(finalTime).toEqual(freshTime);
 });
 
 test("Revalidate path", async ({ page, request }) => {

packages/cloudflare/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @opennextjs/cloudflare
 
+## 1.19.4
+
+### Patch Changes
+
+- [#1221](https://github.com/opennextjs/opennextjs-cloudflare/pull/1221) [`a2679bf`](https://github.com/opennextjs/opennextjs-cloudflare/commit/a2679bf9549f620e1ab0e1900dcc7a6b6ac03e0a) Thanks [@mushan0x0](https://github.com/mushan0x0)! - Stop bundling `@vercel/og` (and its ~1.4 MiB `resvg.wasm`) when the app does not use it.
+
+  Next.js's `externalImport` helper keeps a dynamic `import("next/dist/compiled/@vercel/og/index.edge.js")` in the emitted handler even for apps that never use `ImageResponse` / `opengraph-image`. Previously this module was marked as `external` when `useOg` was `false`, which left Wrangler to resolve and bundle it — pulling in ~800 KiB of JS plus `resvg.wasm` and pushing many Workers over the Cloudflare free-tier 3 MiB gzip limit.
+
+  When `useOg` is `false`, the edge entry is now aliased to the existing `throw.js` shim, so the unreachable dynamic import resolves to a tiny module and the real `@vercel/og` library is no longer pulled into the Worker bundle.
+
+- [#1208](https://github.com/opennextjs/opennextjs-cloudflare/pull/1208) [`2c5b472`](https://github.com/opennextjs/opennextjs-cloudflare/commit/2c5b4729b6a48560b550af820c46c2350e149fa6) Thanks [@edmundhung](https://github.com/edmundhung)! - Use `OPEN_NEXT_BUILD_ID` instead of `NEXT_BUILD_ID` in the cache keys.
+
+  As of Next 16.2 `NEXT_BUILD_ID` is a fixed value when deploymentId is set explicitly.
+
+  See <https://github.com/opennextjs/opennextjs-aws/pull/1144>
+
+- [#1193](https://github.com/opennextjs/opennextjs-cloudflare/pull/1193) [`1e8d232`](https://github.com/opennextjs/opennextjs-cloudflare/commit/1e8d232672353920a8e05e468cf3a5890b82b0f6) Thanks [@conico974](https://github.com/conico974)! - Fix tag cache stale logic
+
+## 1.19.3
+
+### Patch Changes
+
+- [#1215](https://github.com/opennextjs/opennextjs-cloudflare/pull/1215) [`608893e`](https://github.com/opennextjs/opennextjs-cloudflare/commit/608893e63e1ee16d07c7ec42da979657cf2a62bd) Thanks [@vicb](https://github.com/vicb)! - Factor large repeated values in manifests
+
+  This reduce the size of the generated code.
+
+- [#1218](https://github.com/opennextjs/opennextjs-cloudflare/pull/1218) [`f0d0226`](https://github.com/opennextjs/opennextjs-cloudflare/commit/f0d022685b24881a142bb01005ff78089be8c8d3) Thanks [@314systems](https://github.com/314systems)! - remove `process.version` override
+
+  Remove process.version / process.versions.node overrides now that [unjs/unenv#493](https://github.com/unjs/unenv/pull/493) is merged and shipped in [[email protected]](https://github.com/unjs/unenv/releases/tag/v2.0.0-rc.16) (project uses 2.0.0-rc.24)
+
+- [#1199](https://github.com/opennextjs/opennextjs-cloudflare/pull/1199) [`32594d6`](https://github.com/opennextjs/opennextjs-cloudflare/commit/32594d6a921c5ebdbe25f38635bb2c9dabdcbff1) Thanks [@SdSadat](https://github.com/SdSadat)! - fix(cli): fail fast in non-TTY environments instead of hanging on config-creation prompts
+
+  When `open-next.config.ts` (or `wrangler.(toml|json|jsonc)`) is missing, the CLI
+  prompts the user to auto-create it. In non-TTY environments (Cloudflare Workers
+  Builds, Docker, CI) the Enquirer prompt can't read stdin, so the build hangs or
+  fails with a truncated prompt and a cryptic exit code — the user sees
+  `? Missing required open-next.config.ts file, do you want to create one? (Y/n)`
+  and then ` ELIFECYCLE  Command failed with exit code 13`, with no hint at what
+  to do next.
+
+  Now, in non-interactive environments, both prompts throw an actionable error
+  with the exact template to paste (for `open-next.config.ts`) or point at the
+  existing `--skipWranglerConfigCheck` / `SKIP_WRANGLER_CONFIG_CHECK` escape
+  hatch (for the wrangler config). Interactive behavior is unchanged.
+
 ## 1.19.2
 
 ### Patch Changes

packages/cloudflare/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@opennextjs/cloudflare",
 	"description": "Cloudflare builder for next apps",
-	"version": "1.19.2",
+	"version": "1.19.4",
 	"type": "module",
 	"scripts": {
 		"clean": "rimraf dist",
@@ -54,7 +54,8 @@
 	"dependencies": {
 		"@ast-grep/napi": "^0.40.5",
 		"@dotenvx/dotenvx": "catalog:",
-		"@opennextjs/aws": "3.10.2",
+		"@opennextjs/aws": "3.10.4",
+		"ci-info": "^4.2.0",
 		"cloudflare": "^4.4.1",
 		"comment-json": "^4.5.1",
 		"enquirer": "^2.4.1",

packages/cloudflare/src/api/durable-objects/queue.ts

@@ -165,7 +165,7 @@ export class DOQueueHandler extends DurableObject<CloudflareEnv> {
 					"INSERT OR REPLACE INTO sync (id, lastSuccess, buildId) VALUES (?, unixepoch(), ?)",
 					// We cannot use the deduplication id because it's not unique per route - every time a route is revalidated, the deduplication id is different.
 					`${host}${url}`,
-					process.env.__NEXT_BUILD_ID
+					process.env.__OPEN_NEXT_BUILD_ID
 				);
 			}
 			// If everything went well, we can remove the route from the failed state
@@ -238,7 +238,7 @@ export class DOQueueHandler extends DurableObject<CloudflareEnv> {
 				"INSERT OR REPLACE INTO failed_state (id, data, buildId) VALUES (?, ?, ?)",
 				msg.MessageDeduplicationId,
 				JSON.stringify(updatedFailedState),
-				process.env.__NEXT_BUILD_ID
+				process.env.__OPEN_NEXT_BUILD_ID
 			);
 		}
 		// We probably want to do something if routeInFailedState is becoming too big, at least log it
@@ -273,8 +273,8 @@ export class DOQueueHandler extends DurableObject<CloudflareEnv> {
 
 		// Before doing anything else, we clear the DB for any potential old data
 		// TODO: extract this to a function so that it could be called by the user at another time than init
-		this.sql.exec("DELETE FROM failed_state WHERE buildId != ?", process.env.__NEXT_BUILD_ID);
-		this.sql.exec("DELETE FROM sync WHERE buildId != ?", process.env.__NEXT_BUILD_ID);
+		this.sql.exec("DELETE FROM failed_state WHERE buildId != ?", process.env.__OPEN_NEXT_BUILD_ID);
+		this.sql.exec("DELETE FROM sync WHERE buildId != ?", process.env.__OPEN_NEXT_BUILD_ID);
 
 		const failedStateCursor = this.sql.exec<{ id: string; data: string }>("SELECT * FROM failed_state");
 		for (const row of failedStateCursor) {

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,
 		});
 	}

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,
 		});
 	}

packages/cloudflare/src/api/overrides/incremental-cache/regional-cache.ts

@@ -5,6 +5,7 @@ import {
 	IncrementalCache,
 	WithLastModified,
 } from "@opennextjs/aws/types/overrides.js";
+import { compareSemver } from "@opennextjs/aws/utils/semver.js";
 
 import { getCloudflareContext } from "../../cloudflare-context.js";
 import { debugCache, FALLBACK_BUILD_ID, IncrementalCacheEntry, isPurgeCacheEnabled } from "../internal.js";
@@ -31,21 +32,33 @@ type Options = {
 	defaultLongLivedTtlSec?: number;
 
 	/**
-	 * Whether the regional cache entry should be updated in the background or not when it experiences
-	 * a cache hit.
+	 * Whether the regional cache entry should be updated in the background on regional cache hits.
 	 *
-	 * @default `true` in `long-lived` mode when cache purge is not used, `false` otherwise.
+	 * NOTE: Use the default value unless you know what you are doing. It is set to:
+	 * - Next < 16:
+	 *   `true` in `long-lived` mode when cache purge is not used, `false` otherwise.
+	 * - Next >= 16:
+	 *   `!bypassTagCacheOnCacheHit`
 	 */
 	shouldLazilyUpdateOnCacheHit?: boolean;
 
 	/**
-	 * Whether on cache hits the tagCache should be skipped or not. Skipping the tagCache allows requests to be
-	 * handled faster,
+	 * Whether the tagCache should be skipped on regional cache hits.
 	 *
-	 * Note: When this is enabled, make sure that the cache gets purged
-	 *       either by enabling the auto cache purging feature or manually.
+	 * Note:
+	 * - Skipping the tagCache allows requests to be handled faster
+	 * - When `true`, make sure the cache gets purged
+	 *   either by enabling the auto cache purging feature or manually
 	 *
-	 * @default `true` if the auto cache purging is enabled, `false` otherwise.
+	 * `true` is not compatible with SWR types of revalidateTag
+	 * i.e. on Next 16+, anything different than `revalidateTag("tag", { expire: 0 })`.
+	 * That's why the default is `false` for Next 16+ which uses SWR by default.
+	 *
+	 * NOTE: Use the default value unless you know what you are doing. It is set to:
+	 * - Next <16:
+	 *    `true` if the auto cache purging is enabled, `false` otherwise.
+	 * - Next >= 16:
+	 *   `false`
 	 */
 	bypassTagCacheOnCacheHit?: boolean;
 };
@@ -78,17 +91,33 @@ class RegionalCache implements IncrementalCache {
 		private opts: Options
 	) {
 		this.name = this.store.name;
-		// `shouldLazilyUpdateOnCacheHit` is not needed when cache purge is enabled.
-		this.opts.shouldLazilyUpdateOnCacheHit ??= this.opts.mode === "long-lived" && !isPurgeCacheEnabled();
-	}
 
-	get #bypassTagCacheOnCacheHit(): boolean {
-		if (this.opts.bypassTagCacheOnCacheHit !== undefined) {
-			return this.opts.bypassTagCacheOnCacheHit;
+		// `globalThis.nextVersion` is only defined at runtime but not when the Open Next build runs.
+		// The options do no matter at build time so we can skip setting them.
+		const { nextVersion } = globalThis;
+		if (nextVersion) {
+			if (compareSemver(nextVersion, "<", "16")) {
+				// Next < 16
+				this.opts.shouldLazilyUpdateOnCacheHit ??= this.opts.mode === "long-lived" && !isPurgeCacheEnabled();
+				this.opts.bypassTagCacheOnCacheHit ??= isPurgeCacheEnabled();
+			} else {
+				// Next >= 16
+				this.opts.bypassTagCacheOnCacheHit ??= false;
+				if (this.opts.bypassTagCacheOnCacheHit) {
+					debugCache(
+						"RegionalCache",
+						`bypassTagCacheOnCacheHit is not recommended for Next 16+ as it is not compatible with SWR tags. Make sure to always use \`revalidateTag\` with \`{ expire: 0 }\` if you want to bypass the tag cache.`
+					);
+				}
+				this.opts.shouldLazilyUpdateOnCacheHit ??= !this.opts.bypassTagCacheOnCacheHit;
+				if (this.opts.shouldLazilyUpdateOnCacheHit !== this.opts.bypassTagCacheOnCacheHit) {
+					debugCache(
+						"RegionalCache",
+						`\`shouldLazilyUpdateOnCacheHit\` and \`bypassTagCacheOnCacheHit\` are mutually exclusive for Next 16+.`
+					);
+				}
+			}
 		}
-
-		// When `bypassTagCacheOnCacheHit` is not set, we default to whether the automatic cache purging is enabled or not
-		return isPurgeCacheEnabled();
 	}
 
 	async get<CacheType extends CacheEntryType = "cache">(
@@ -123,7 +152,7 @@ class RegionalCache implements IncrementalCache {
 
 				return {
 					...responseJson,
-					shouldBypassTagCache: this.#bypassTagCacheOnCacheHit,
+					shouldBypassTagCache: this.opts.bypassTagCacheOnCacheHit,
 				};
 			}
 
@@ -190,7 +219,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"}`;
 	}