Add Checkout Kit CDN module loader

[kiftio]

What changes are you making?

Publish Checkout Kit Web to Shopify's CDN alongside npm.

Loader. A major-versioned ES module at https://cdn.shopify.com/checkout-kit/v<major>/web-components.js registers components on demand:

<script type="module">
  import {loadComponents} from 'https://cdn.shopify.com/checkout-kit/v4/web-components.js';
  await loadComponents(['shopify-checkout']);
</script>

The URL is evergreen within a major: compatible updates ship automatically; a breaking change needs a new major path. Implementation chunks are content-hashed deployment details, not public URLs. The loader also exports version and supportedComponents. A maintainer-only v<major>/unstable/ channel exists for exercising prereleases through the real CDN; it is not a supported entrypoint and is documented as such.

Release workflow (web-publish.yml, runs on web/X.Y.Z releases as today):

• Uploads content-hashed chunks before the loader that references them.
• The stable URL updates only for a non-prerelease version, not flagged as a GitHub prerelease, published to npm latest; everything else goes to the unstable channel for its major.
• A token-only pre-flight confirms the deploy identity holds the bucket permissions the upload needs, before anything irreversible happens and without leaving credentials on disk for package code. Full authentication happens only after npm publication; npm publish runs with --ignore-scripts so the built-and-verified dist/ is what ships.
• Re-running a release (or a failed manual run) redeploys the CDN assets for an already-published version, which doubles as rollback. A fresh manual dispatch of an already-published version is refused, since main may no longer match the published tarball.
• The CDN applies one cache policy to every /checkout-kit/ path, so the workflow sets no per-object Cache-Control; docs describe the ~30 minute propagation window and a bad-deploy runbook.

npm package. import '@shopify/checkout-kit' still registers <shopify-checkout>. Generated chunks are marked side-effectful; a built-package test bundles as a consumer and checks registration. Registration is skipped if the element is already defined, so loading Checkout Kit twice (npm bundle plus CDN loader) does not throw. package.json exports are unchanged, so the new dist/ layout is not consumer-visible.

Housekeeping. The packed-files snapshot normalises content hashes so it does not churn on every source change; the new tests use vitest like the rest of the package (the built-package check has its own config and runs from pnpm verify); root *.ts config files are now covered by the oxfmt globs; dependency-cruiser treats src/cdn-loader.ts as a second public entrypoint.

Details: platforms/web/CDN-PUBLISHING.md, platforms/web/RELEASING.md.

Known limitation. There is no supported path yet for patching an older major after a new major ships (npm has one latest; manual dispatch runs from main). Tracked as a follow-up before 5.0.0.

Open question — entrypoint filename. The loader is published as /checkout-kit/v4/web-components.js, mirroring Storefront Web Components (/storefront/web-components.js, per-component files at /storefront/web-components/<name>.js) and leaving /checkout-kit/v4/web-components/shopify-checkout.js as the natural slot for a per-component drop-in later. The earlier draft used /checkout-kit/v4/checkout-kit.js (payments-SDK style, e.g. stripe.js), which repeats the namespace. One caveat with the Storefront parallel: ours is a loader you call, not a side-effect bundle, and the docs say so. This is a one-way door after first publish — please weigh in if you prefer the brand-named file.

How to test

cd platforms/web
pnpm lint && pnpm test
pnpm build && pnpm verify && pnpm compare-snapshot
actionlint .github/workflows/web-publish.yml   # from the repo root

pnpm verify bundles a consumer with import "@shopify/checkout-kit" and checks <shopify-checkout> registers, and loads the built CDN loader from isolated v4/ and v4/unstable/ directory layouts via native ESM.

Once merged, a workflow_dispatch dry run from main exercises the pre-flight against the real deploy identity without publishing anything. The first real deployment will be a prerelease to the unstable channel; the stable URL becomes available with 4.0.0.

---

Before you merge

Important

• I've added tests to support my implementation
• I have read and agree with the Contribution Guidelines
• I have read and agree with the Code of Conduct
• I've updated the relevant platform README (platforms/web/README.md)

[github-actions]

Web — Coverage Report

Lines	Statements	Branches	Functions
	95.41% (458/480)	85.92% (238/277)	97.39% (112/115)

[github-actions]

Bundle Size Budgets

Budget	Size	Limits	Result
Web JavaScript (uncompressed)	35.25 KiB (+1.32 KiB)	35 KiB soft / 50 KiB hard	✅ Accepted by @kiftio: Adds a second distribution entrypoint (CDN loader web-components.js, 969 B) and an npm re-export shim (276 B); the shared component chunk grew 104 B for the registration guard and chunk (comment)

• web: accepted 1 exceeded metric(s).

Bundle and package size

Web bundle sizes cover shipped runtime JavaScript. Package sizes cover the full published archive, including any source maps, declarations, and documentation it contains.

Platform	Measurement	Compression	Base	Head	Delta
Web	JavaScript bundle	Uncompressed	33.9 KiB	35.2 KiB	+1.3 KiB
Web	JavaScript bundle	gzip	10.5 KiB	11.3 KiB	+834 B
Web	npm package (.tgz)	gzip	91.0 KiB	95.4 KiB	+4.4 KiB

Web package files (uncompressed)

These are uncompressed file sizes; they do not sum to the compressed package size above.

File	Base	Head	Delta
dist/assets/shopify-checkout-CMRYy2le.js.map	—	251.6 KiB	+251.6 KiB
dist/index.js.map	251.0 KiB	—	-251.0 KiB
dist/custom-elements.json	48.8 KiB	51.4 KiB	+2.6 KiB
dist/index.d.ts	48.0 KiB	48.0 KiB	0 B
dist/assets/shopify-checkout-CMRYy2le.js	—	34.0 KiB	+34.0 KiB
dist/index.js	33.9 KiB	276 B	-33.7 KiB
README.md	20.8 KiB	21.5 KiB	+679 B
dist/web-components.js.map	—	5.9 KiB	+5.9 KiB
package.json	3.6 KiB	3.8 KiB	+202 B
dist/web-components.d.ts	—	1.3 KiB	+1.3 KiB
LICENSE	1.1 KiB	1.1 KiB	0 B
dist/web-components.js	—	969 B	+969 B

How sizes are measured

Measured from the PR base SHA and PR head SHA. Web bundle rows sum shipped .js, .mjs, and .cjs files under dist/, excluding source maps and declarations. The gzip bundle size sums files compressed individually with gzip -n -9. npm package sizes are gzip-compressed .tgz archives; Android AAR sizes are ZIP archives. Package sizes are not final app binary sizes.

[kiftio]

/accept-size web Adds a second distribution entrypoint (CDN loader web-components.js, 969 B) and an npm re-export shim (276 B); the shared component chunk grew 104 B for the registration guard and chunk
boundary. No consumer downloads both entrypoints: npm consumers see +380 B, CDN consumers had nothing before.