@bigcommerce/catalyst 1.2.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bigcommerce/catalyst",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -15,7 +15,7 @@
     "templates"
   ],
   "engines": {
-    "node": "^20.0.0 || ^22.0.0 || ^24.0.0"
+    "node": "^22.0.0 || ^24.0.0"
   },
   "dependencies": {
     "@commander-js/extra-typings": "^14.0.0",
@@ -35,6 +35,7 @@
     "semver": "^7.7.4",
     "std-env": "^3.9.0",
     "tar": "^7.5.7",
+    "tldts": "^7.4.12",
     "yocto-spinner": "^1.0.0",
     "zod": "^4.0.5"
   },
@@ -57,7 +58,12 @@
     "@bigcommerce/eslint-config-catalyst": "^1.0.0"
   },
   "peerDependencies": {
-    "@opennextjs/cloudflare": "1.17.3"
+    "@opennextjs/cloudflare": "^1.17.3"
+  },
+  "peerDependenciesMeta": {
+    "@opennextjs/cloudflare": {
+      "optional": true
+    }
   },
   "scripts": {
     "dev": "tsup --watch",

package/templates/open-next.config.ts

@@ -1,17 +1,72 @@
 import { defineCloudflareConfig, type OpenNextConfig } from '@opennextjs/cloudflare';
-import { purgeCache } from '@opennextjs/cloudflare/overrides/cache-purge/index';
 import r2IncrementalCache from '@opennextjs/cloudflare/overrides/incremental-cache/r2-incremental-cache';
 import { withRegionalCache } from '@opennextjs/cloudflare/overrides/incremental-cache/regional-cache';
-import doQueue from '@opennextjs/cloudflare/overrides/queue/do-queue';
 import queueCache from '@opennextjs/cloudflare/overrides/queue/queue-cache';
 import doShardedTagCache from '@opennextjs/cloudflare/overrides/tag-cache/do-sharded-tag-cache';
 
+// OpenNext's `doQueue` cannot be used on native hosting: its Durable Object
+// requires a `WORKER_SELF_REFERENCE` service binding, which a dispatch-namespace
+// script cannot have. See LTRAC-1457 for why the alternatives were rejected.
+//
+// No binding is required. The revalidation is a HEAD request to the page's own
+// public URL carrying the build-time preview secret, which is exactly what the
+// Durable Object issues once it holds the service handle. Sending it with a
+// plain `fetch` leaves and re-enters through the dispatch router and arrives at
+// the same Worker. `global_fetch_strictly_public` is set, so the subrequest is
+// not short-circuited internally.
+//
+// Wrapped in `queueCache` below so concurrent stale hits for one path collapse
+// into a single revalidation. What is lost relative to the Durable Object is its
+// retry and max-concurrency handling; a failed revalidation is retried on the
+// next stale hit rather than by the queue itself.
+
+// Matches the Durable Object's default. Without a bound, a hanging revalidation
+// would sit in `waitUntil` holding the invocation alive.
+const REVALIDATION_TIMEOUT_MS = 10_000;
+
+const selfFetchQueue = {
+  name: 'self-fetch-queue',
+  async send({ MessageBody: { host, url } }: { MessageBody: { host: string; url: string } }) {
+    const protocol = host.includes('localhost') ? 'http' : 'https';
+
+    const response = await fetch(`${protocol}://${host}${url}`, {
+      method: 'HEAD',
+      headers: {
+        // Inlined at build time; authorizes the revalidation. The name is
+        // Next's, so the leading underscores are not ours to rename.
+        // eslint-disable-next-line no-underscore-dangle
+        'x-prerender-revalidate': process.env.__NEXT_PREVIEW_MODE_ID ?? '',
+        'x-isr': '1',
+      },
+      signal: AbortSignal.timeout(REVALIDATION_TIMEOUT_MS),
+    });
+
+    // `fetch` resolves for 4xx/5xx, so a failed regeneration would otherwise be
+    // indistinguishable from success. Throwing surfaces it: `queueCache` logs
+    // the error and, with `waitForQueueAck`, skips caching the attempt — so the
+    // next stale hit retries rather than the failure being swallowed. Silent
+    // failure is the exact bug this queue exists to fix.
+    if (!response.ok) {
+      throw new Error(`Revalidation of ${url} failed with status ${response.status}`);
+    }
+  },
+};
+
 const cloudflareConfig = defineCloudflareConfig({
+  // The absence of `cachePurge` and `bypassTagCacheOnCacheHit` is deliberate.
+  // Invalidating regional (Cache API) entries needs either a CDN purge that
+  // evicts them or a tag-cache check on every hit; this takes the second.
+  //
+  // Do not restore `cachePurge` without reading LTRAC-1458 first. OpenNext's
+  // `isPurgeCacheEnabled()` checks only whether it is *declared*, never whether
+  // it can authenticate, and declaring it turns off both
+  // `shouldLazilyUpdateOnCacheHit` and the tag check. A purge that cannot
+  // authenticate therefore leaves entries neither purged, nor refreshed from R2,
+  // nor tag-checked, and `revalidateTag` silently stops working.
   incrementalCache: withRegionalCache(r2IncrementalCache, {
     mode: 'long-lived',
-    bypassTagCacheOnCacheHit: true,
   }),
-  queue: queueCache(doQueue, {
+  queue: queueCache(selfFetchQueue, {
     regionalCacheTtlSec: 5,
     waitForQueueAck: true,
   }),
@@ -30,11 +85,17 @@ const cloudflareConfig = defineCloudflareConfig({
     },
   }),
   enableCacheInterception: false,
-  cachePurge: purgeCache({ type: 'durableObject' }),
 });
 
 const config: OpenNextConfig = {
-  buildCommand: 'node_modules/.bin/next build',
+  // Invoke Next through `node` on its published bin rather than the
+  // `node_modules/.bin/next` shim. OpenNext runs this string via
+  // `execSync`, which shells out to cmd.exe on native Windows — where the
+  // extensionless POSIX shim and forward-slash path both fail to resolve.
+  // Calling `node <bin>` works identically across sh and cmd.exe (node.exe
+  // accepts forward slashes) while still bypassing the project's `build`
+  // script so the `generate` step is skipped.
+  buildCommand: 'node ./node_modules/next/dist/bin/next build',
   ...cloudflareConfig,
 };