LTRAC-1732: build(cli) - Bump @opennextjs/cloudflare to 1.20.6 - #3203
Merged
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
🦋 Changeset detectedLatest commit: 4ce6c0b The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
Contributor
Bundle Size ReportComparing against baseline from No bundle size changes detected. |
jorgemoya
force-pushed
the
jorgemoya/ltrac-1732-opennext-1-20-5
branch
from
September 2, 2026 16:24
dad23e0 to
a589857
Compare
jorgemoya
force-pushed
the
jorgemoya/ltrac-1732-opennext-1-20-5
branch
from
September 2, 2026 16:31
a589857 to
620157a
Compare
jorgemoya
force-pushed
the
jorgemoya/ltrac-1732-opennext-1-20-5
branch
from
September 2, 2026 16:42
620157a to
9f87fe8
Compare
jorgemoya
force-pushed
the
jorgemoya/ltrac-1732-opennext-1-20-5
branch
from
September 2, 2026 17:04
9f87fe8 to
2b46c2e
Compare
jorgemoya
changed the title
jorgemoya
force-pushed
the
jorgemoya/ltrac-1732-opennext-1-20-5
branch
from
September 2, 2026 17:11
2b46c2e to
37d5565
Compare
jorgemoya
force-pushed
the
jorgemoya/ltrac-1732-opennext-1-20-5
branch
from
September 2, 2026 17:25
37d5565 to
4acebf5
Compare
Contributor
Unlighthouse Performance Comparison — VercelComparing PR preview deployment Unlighthouse scores vs production Unlighthouse scores. Summary ScoreAggregate score across all categories as reported by Unlighthouse.
Category Scores
Core Web Vitals
|
jorgemoya
force-pushed
the
jorgemoya/ltrac-1732-opennext-1-20-5
branch
from
September 2, 2026 19:28
4acebf5 to
7a3be0b
Compare
jorgemoya
force-pushed
the
jorgemoya/ltrac-1732-opennext-1-20-5
branch
from
September 2, 2026 19:36
7a3be0b to
9a99d40
Compare
jorgemoya
force-pushed
the
jorgemoya/ltrac-1732-opennext-1-20-5
branch
from
September 2, 2026 19:54
9a99d40 to
c930d66
Compare
jorgemoya
marked this pull request as ready for review
September 2, 2026 20:01
parthshahp
reviewed
Sep 2, 2026
Contributor
There was a problem hiding this comment.
Could we maybe make the comments more succinct if we need them? At this length they don't seem that useful
Contributor
Author
There was a problem hiding this comment.
Good call, cleaning them up.
jorgemoya
force-pushed
the
jorgemoya/ltrac-1732-opennext-1-20-5
branch
from
September 3, 2026 14:33
c930d66 to
c2f3060
Compare
jorgemoya
force-pushed
the
jorgemoya/ltrac-1732-opennext-1-20-5
branch
from
September 3, 2026 14:41
c2f3060 to
6491f7b
Compare
Contributor
Author
|
Local test: |
Move the Cloudflare adapter from 1.17.3 to 1.20.6 and the Wrangler version the
build shells out to from 4.90.0 to 4.128.0.
Remove the stray @opennextjs/cloudflare dependency from the repo root. It was
never meant to be there -- the adapter only belongs to a project that has been
transformed for Commerce Hosting. It was also redundant: autoInstallPeers is on,
so the peer declared by packages/catalyst already installs the adapter into that
package, which is what resolves it for the Cloudflare context contract spec and
for tsc typechecking templates/open-next.config.ts (its tsconfig sets no
`include`). Wrangler is deliberately not declared anywhere either -- the build
invokes a pinned version through `dlx`.
Dropping the root declaration is also what fixed the stale Wrangler pin. pnpm
had auto-installed 4.31.0 and recorded it in the lockfile, short of even the old
^4.65.0 peer, and it treats auto-installed peer resolutions as sticky -- pnpm
update, pnpm install --force, and stripping the lock entries all failed to move
it. Letting it resolve fresh lands 4.128.0 with no OpenNext peer warnings left.
Offer to move a stale adapter pin on the shared build path, and reinstall when
it moves. The pin lives in the project's own package.json and deploy skips
setupCommerceHosting once isTransformed is true, so bumping the constant alone
never reaches an existing Commerce Hosting project. `catalyst upgrade` cannot
move it either: the adapter is injected into the project and absent from the
upstream tree, so no 3-way merge ever sees it, which is the same reason
findStaleCli checks the CLI's own pin out-of-band.
The check lives in buildCatalystProject rather than in a single command, so
`catalyst build` and `catalyst deploy` both get it exactly once, immediately
before the adapter is invoked and early enough for the install to land first.
`catalyst deploy --prebuilt` skips the build entirely, so it warns instead --
changing dependencies there would upload a bundle the new adapter never
compiled.
reconcileOpenNextVersion only acts on a project that is genuinely behind
(validRange -> satisfies -> minVersion -> lt), so one pinned ahead, one on a
range that already admits the target, and one on a git or file specifier are all
left alone. It also refuses when the project's Next version is older than the
adapter supports, sending the user to `catalyst upgrade` instead of handing them
an unsupported peer set, and never prompts without a TTY: pnpm treats the
lockfile as frozen in CI, so the install that must follow would fail the deploy.
Every path that declines to act reports the exact command to run.
OPENNEXT_REQUIRED_NEXT_RANGE records the `next` peer range the pinned adapter
declares, so the compatibility gate has something to check against. It is
hand-synced with OPENNEXT_CLOUDFLARE_VERSION -- read it off the new adapter's
peerDependencies.next when bumping.
Keep the adapter peer an optional ^1.17.3 range. An exact peer would make the
upgraded CLI unresolvable for projects still on the older adapter -- npm fails
with ERESOLVE on a present-but-mismatched peer, and `optional` does not excuse
that, only an absent one -- so those merchants could never install the CLI
version that offers the upgrade. Optional keeps it quiet on projects hosted
somewhere that never installs the adapter at all.
Keep OPENNEXT_CLOUDFLARE_VERSION an exact version. core's Cloudflare KV adapter
reads globalThis[Symbol.for('__cloudflare-context__')] directly, and if a
version changed that key it would silently return null and every native-hosted
store would quietly degrade to an in-process cache with no error and no signal.
cloudflare-context-symbol.spec.ts guards that by asserting this literal. 1.20.6
was verified against it: the symbol key, index.d.ts, config.d.ts, all four
override subpaths and their types, and the three Durable Object class names are
identical to 1.20.5.
Drop Node 20 from the CLI's engines range. Every Wrangler release satisfying the
adapter's ^4.125.0 peer requires Node 22 or later, so advertising Node 20 would
be inaccurate -- and already was, since the previously pinned wrangler@4.90.0
also declares node >=22.0.0, meaning catalyst build and deploy could not work on
Node 20 before this change either. What does regress is catalyst start, which
ran against a locally resolved 4.31.0 supporting Node 18+.
The API this repo depends on is unchanged: defineCloudflareConfig, the
OpenNextConfig type, the four override subpaths the generated open-next.config
imports, ShardedDOTagCacheOptions, and the Queue interface selfFetchQueue
implements. The Durable Object class names and compatibility flags Ignition
mirrors are unchanged too, so no Ignition change is required.
build.spec.ts now imports WRANGLER_VERSION rather than duplicating the literal,
so the two cannot drift again.
Refs LTRAC-1732
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
jorgemoya
force-pushed
the
jorgemoya/ltrac-1732-opennext-1-20-5
branch
from
September 3, 2026 14:56
6491f7b to
4ce6c0b
Compare
parthshahp
approved these changes
Sep 3, 2026
This was referenced Sep 3, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Linear: LTRAC-1732
Follows #3202 (Next.js 16.3.4), which this required — 1.20.6's peer range is
next >=15.5.24 <16 || >=16.3.3.What/Why?
Moves the Cloudflare adapter 1.17.3 → 1.20.6 and the Wrangler version the build shells out to 4.90.0 → 4.128.0.
Both leave this repo's dependency graph. The adapter and Wrangler only belong to a project transformed for Commerce Hosting, so the root
package.jsonshould never have carried the adapter as a dependency. It moves to a devDependency ofpackages/catalyst, which is where it is actually needed:cloudflare-context-symbol.spec.tsimports it, and tsc typecheckstemplates/open-next.config.ts(the tsconfig sets noinclude). Wrangler is now declared nowhere — the build invokes a pinned version viadlx, and in the monorepo pnpm resolves it from the adapter's own^4.125.0peer.That is also what fixed the stale Wrangler pin, rather than declaring it. pnpm had auto-installed 4.31.0 and recorded it in the lockfile — short of even the old
^4.65.0peer — and it treats auto-installed peer resolutions as sticky, sopnpm update,pnpm install --force, and stripping the lock entries all failed to move it. Removing the root declaration and letting it resolve fresh lands 4.128.0 with no OpenNext peer warnings left.API compatibility was verified by diffing the published tarballs, not by reading the changelog. Unchanged:
defineCloudflareConfig, theOpenNextConfigtype (index.d.tsandconfig.d.tsbyte-identical), the four override subpaths the generatedopen-next.config.tsimports,ShardedDOTagCacheOptions, and theQueue/QueueMessageinterfaces the customselfFetchQueueimplements.@opennextjs/awsgoes 3.9.16 → 4.1.3, but v4.0.0 was a mislabeled major — upstream says it "should really have been 3.10.5" with no breaking changes.No Ignition change is required, checked against the Go source rather than assumed. Ignition pins neither the adapter nor Wrangler (no version constant, no
exec.Command, no Node toolchain — it consumes a pre-builtworker.js+/assets/). What it does mirror is unchanged: the compat flags inpkg/cloudflare/upload/metadata.go(1.20.5 needs the same singlenodejs_compatflag as 1.17.3) and the DO migration tag +DOQueueHandler/DOShardedTagCache/BucketCachePurgeclass names inpkg/cloudflare/upload/migrations/migrations.go.Node 20 dropped from
engines.WRANGLER_VERSIONis whatcatalyst build/deployinvoke, and every Wrangler satisfying the adapter's^4.125.0peer requires Node ≥22 (the last supporting Node 20 is 4.86.0, below the floor). It was already inaccurate: the previouswrangler@4.90.0pin also declaresnode >=22.0.0, so build/deploy could not work on Node 20 before this either. What genuinely regresses iscatalyst start, which ran against the locally resolved 4.31.0 (Node ≥18).catalyst buildandcatalyst deploynow offer to move the adapter pin, and reinstall when it moves. The pin lives in the project's ownpackage.jsonanddeployskipssetupCommerceHostingonceisTransformed, so bumping the constant alone never reaches an existing Commerce Hosting project.catalyst upgradecannot move it either — the adapter is injected into the project and absent from the upstream tree, so no 3-way merge ever sees it (upgrade.ts:49-51records the same constraint for the CLI's own pin, which is whyfindStaleClichecks it out-of-band).The check lives in
buildCatalystProject, the path both commands share, so it runs exactly once immediately before the adapter is invoked — early enough for the install to land first. Putting it in a single command would have missed thecatalyst build→deploy --prebuiltflow thatsetupCoreProjectscaffolds scripts for.reconcileOpenNextVersionacts only on a project genuinely behind (validRange→satisfies→minVersion→lt), so one pinned ahead, one on a range that already admits the target, and one on a git/file specifier are left alone. Four gates stand before it writes anything:catalyst upgrade, don't offerdeploy --prebuiltEvery path that declines to act reports the exact command to run.
OPENNEXT_REQUIRED_NEXT_RANGEbacks the compatibility gate and is hand-synced with the version constant — read it off the new adapter'speerDependencies.nextwhen bumping.The peer stays an optional
^1.17.3range, deliberately. An exact peer would make the upgraded CLI unresolvable for merchants still on the old adapter, so they could never install the version that offers the upgrade. Verified rather than assumed: npm fails withERESOLVE — Conflicting peer dependencyon a present-but-mismatched peer even when it is markedoptional;optionalexcuses only an absent peer, which is what keeps it quiet for projects hosted somewhere that never installs the adapter.Areas worth careful review
reconcileOpenNextVersionand its call site indeploy.ts— the only behavioural change; everything else is dependency and version bookkeeping.enginesnarrowing, released asminor.enginesis advisory (pnpm warns, npm doesn't block withoutengine-strict) and no working Node 20 configuration is being removed, but flagging it as a judgement call.Rollout/Rollback
Rollout is gradual, not fleet-wide: since Ignition doesn't pin the adapter, deployed stores keep running whatever version they last built with. The bump only takes effect per-store on next deploy.
On that first deploy,
DOShardedTagCacheruns an in-place SQLite migration addingstale/expirecolumns to itsrevalidationstable, backing the SWRrevalidateTagsupport added in 1.19.0. It is guarded and automatic. Rollback to 1.17.3 is tolerable — the older code ignores the extra columns.withRegionalCachedefaults were re-derived for Next 16 (bypassTagCacheOnCacheHitnow defaultsfalse,shouldLazilyUpdateOnCacheHitto!bypassTagCacheOnCacheHit). The generated config declares neither (see LTRAC-1458), so effective behaviour is unchanged and no config edit is needed.Rollback is reverting this PR; no data migration blocks rolling forward.
Testing
tsc --noEmit,eslint . --max-warnings 0,tsupbuild — all cleancloudflare-context-symbol.spec.tspasses against the real 1.20.6 — confirming both that the__cloudflare-context__keycore/lib/kv/adapters/cloudflare-kv.tsreads directly is unchanged, and that the adapter still resolves after moving to a devDependencypnpm install --frozen-lockfileclean after rebasing onto merged canarywrangler@4.31.0is gone from the lockfiletest:coveragethreshold already fails on canary and CI runspnpm run test, so this is a marginal improvement, not a regressionNot covered: a real
catalyst build/ OpenNext bundle, which needs store credentials. This is the main residual risk, because 1.20.3 rewrote Turbopack wasm-helper patching for Next 16.3's emit shape, and it would also confirm the output still fits Ignition's bundle limits (worker.js≤ 40 MiB, each asset ≤ 25 MiB, ≤ 1000 files perpkg/cloudflare/bundle/limits.go). Worth running before merge.Migration
None for this repo. Merchants on an older adapter pin are now prompted on deploy to move it, with the safe-to-take gates above.
Refs LTRAC-1732