From 32e96f1e9856ef819751723ca85a6d6ce21b97ec Mon Sep 17 00:00:00 2001
From: Daniel Kift <daniel.kift@shopify.com>
Date: Thu, 8 Oct 2026 10:22:28 +0100
Subject: [PATCH 1/3] Organize Web components and add explicit checkout import

---
 platforms/web/README.md                       |  37 ++++--
 platforms/web/dependency-cruiser.config.mjs   |   2 +-
 platforms/web/package.json                    |  26 ++--
 platforms/web/package.snapshot.json           |   5 +-
 platforms/web/sample/README.md                |   2 +-
 platforms/web/sample/main.ts                  |   2 +-
 platforms/web/sample/tsconfig.json            |   3 +-
 platforms/web/sample/vite.config.ts           |  11 +-
 platforms/web/scripts/npm-package.test.ts     | 122 ++++++++++++++++++
 platforms/web/scripts/tsconfig.json           |  10 ++
 .../shopify-checkout}/browser-capabilities.ts |   0
 .../shopify-checkout}/checkout-events.ts      |   4 +-
 .../checkout-protocol.test.ts                 |   6 +-
 .../shopify-checkout}/checkout-window.test.ts |   8 +-
 .../shopify-checkout}/checkout.types.ts       |   6 +-
 .../shopify-checkout/register.ts}             |   2 +-
 .../shopify-checkout/shopify-checkout.css}    |   0
 .../shopify-checkout.test.ts}                 |  10 +-
 .../shopify-checkout/shopify-checkout.ts}     |  20 +--
 platforms/web/src/index.ts                    |  21 ++-
 platforms/web/test/e2e/README.md              |   2 +-
 platforms/web/test/e2e/fixtures/host.html     |   2 +-
 platforms/web/test/e2e/server.mjs             |  14 +-
 platforms/web/vite.config.ts                  |  12 +-
 platforms/web/vitest.package.config.ts        |  11 ++
 scripts/test/changed_file_filters_test.rb     |   2 +-
 26 files changed, 268 insertions(+), 72 deletions(-)
 create mode 100644 platforms/web/scripts/npm-package.test.ts
 create mode 100644 platforms/web/scripts/tsconfig.json
 rename platforms/web/src/{ => components/shopify-checkout}/browser-capabilities.ts (100%)
 rename platforms/web/src/{ => components/shopify-checkout}/checkout-events.ts (94%)
 rename platforms/web/src/{ => components/shopify-checkout}/checkout-protocol.test.ts (99%)
 rename platforms/web/src/{ => components/shopify-checkout}/checkout-window.test.ts (99%)
 rename platforms/web/src/{ => components/shopify-checkout}/checkout.types.ts (97%)
 rename platforms/web/src/{checkout-web-component.ts => components/shopify-checkout/register.ts} (75%)
 rename platforms/web/src/{checkout.css => components/shopify-checkout/shopify-checkout.css} (100%)
 rename platforms/web/src/{checkout.test.ts => components/shopify-checkout/shopify-checkout.test.ts} (98%)
 rename platforms/web/src/{checkout.ts => components/shopify-checkout/shopify-checkout.ts} (98%)
 create mode 100644 platforms/web/vitest.package.config.ts

diff --git a/platforms/web/README.md b/platforms/web/README.md
index a7f4b4443..d2f2e15b9 100644
--- a/platforms/web/README.md
+++ b/platforms/web/README.md
@@ -86,13 +86,18 @@ Once the first stable `4.0.0` ships, the standard `pnpm add @shopify/checkout-ki
 
 ## Basic Usage
 
-Import the package once anywhere in your application. The import has a side
-effect — it registers `<shopify-checkout>` with `customElements`:
+Import the component once anywhere in your application. This entry registers
+only `<shopify-checkout>` with `customElements`:
 
 ```ts
-import '@shopify/checkout-kit';
+import '@shopify/checkout-kit/shopify-checkout';
 ```
 
+Components use separate entry points within the same npm package. Import only
+the components you need. The existing root import (`@shopify/checkout-kit`)
+continues to register `<shopify-checkout>` for compatibility; it will not
+automatically register additional components.
+
 Then render the element anywhere in your HTML and call `open()` to present
 checkout:
 
@@ -106,7 +111,7 @@ checkout:
 <button id="buy-now">Buy now</button>
 
 <script type="module">
-  import '@shopify/checkout-kit';
+  import '@shopify/checkout-kit/shopify-checkout';
 
   const checkout = document.getElementById('checkout');
   document.getElementById('buy-now').addEventListener('click', () => {
@@ -127,7 +132,7 @@ below for details on how to obtain a checkout URL.
 If you'd rather not declare the element in HTML, create one from JavaScript:
 
 ```ts
-import '@shopify/checkout-kit';
+import '@shopify/checkout-kit/shopify-checkout';
 import type {ShopifyCheckout} from '@shopify/checkout-kit';
 
 const checkout = document.createElement('shopify-checkout') as ShopifyCheckout;
@@ -145,8 +150,8 @@ checkout.close();
 ```
 
 The `ShopifyCheckout` class is also exported directly when you need the
-constructor. The package has a single entry point, so this named import also
-registers `<shopify-checkout>` with `customElements`:
+constructor. This existing root import also registers `<shopify-checkout>`
+with `customElements`:
 
 ```ts
 import {ShopifyCheckout} from '@shopify/checkout-kit';
@@ -168,7 +173,7 @@ subscribing to Checkout Kit events.
 
 ```tsx
 import {useEffect, useRef} from 'react';
-import '@shopify/checkout-kit';
+import '@shopify/checkout-kit/shopify-checkout';
 import type {ShopifyCheckout} from '@shopify/checkout-kit';
 
 export function BuyNowButton({checkoutUrl}: {checkoutUrl: string}) {
@@ -239,7 +244,7 @@ declare module 'react' {
 > the `react` module.
 
 > [!NOTE]
-> The `import '@shopify/checkout-kit'` side effect registers the element with
+> The `import '@shopify/checkout-kit/shopify-checkout'` side effect registers the element with
 > `customElements` and touches browser-only globals, so it must run on the
 > client. In server-rendered frameworks (Next.js, Remix), keep the import and
 > the component in a client component — e.g. add `'use client'` to the top of
@@ -614,3 +619,17 @@ conventions, and one-time setup notes.
 ## License
 
 Shopify's Checkout Kit is provided under an [MIT License](LICENSE).
+
+## Source organization
+
+Component implementations live in `src/components/<component-name>/`, with an
+explicitly named implementation file such as
+`src/components/shopify-checkout/shopify-checkout.ts`. Keep component-specific
+styles, events, types, and tests alongside it; `register.ts` registers its custom
+element. Import files directly rather than adding component barrel files.
+
+New components such as `accelerated-checkouts`, `universal-checkout`, and
+`shop-wallet` should follow the same layout when added. Shared models and helpers
+stay outside component directories. `src/index.ts` remains the public npm entry
+for `@shopify/checkout-kit`. Expose each component through its own package subpath
+pointing to `register.ts`; do not add every component registration to the root entry.
diff --git a/platforms/web/dependency-cruiser.config.mjs b/platforms/web/dependency-cruiser.config.mjs
index a261e4542..00f35613f 100644
--- a/platforms/web/dependency-cruiser.config.mjs
+++ b/platforms/web/dependency-cruiser.config.mjs
@@ -21,7 +21,7 @@ export default {
         pathNot: [
           "(^|/)node_modules/",
           "^package\\.json$",
-          "^src/checkout\\.types\\.ts$",
+          "^src/components/shopify-checkout/checkout\\.types\\.ts$",
           "\\.d\\.ts$",
           "\\.test\\.ts$",
           "\\.test-helpers\\.ts$",
diff --git a/platforms/web/package.json b/platforms/web/package.json
index 1f78281b0..b6bb556e0 100644
--- a/platforms/web/package.json
+++ b/platforms/web/package.json
@@ -28,13 +28,20 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./shopify-checkout": {
+      "types": "./dist/shopify-checkout.d.ts",
+      "import": "./dist/shopify-checkout.js",
+      "default": "./dist/shopify-checkout.js"
+    },
     "./custom-elements.json": "./dist/custom-elements.json",
     "./package.json": "./package.json"
   },
   "sideEffects": [
     "./src/index.ts",
-    "./src/checkout-web-component.ts",
-    "./dist/index.js"
+    "./src/components/shopify-checkout/register.ts",
+    "./dist/index.js",
+    "./dist/shopify-checkout.js",
+    "./dist/chunks/*.js"
   ],
   "files": [
     "LICENSE",
@@ -57,22 +64,23 @@
     "dev": "vite build --watch",
     "test": "vitest run --coverage",
     "test:watch": "vitest",
-    "lint": "pnpm run typecheck && pnpm run sample:typecheck && pnpm run lint:compat && pnpm run lint:dependencies && pnpm run lint:js && pnpm run format:check",
+    "lint": "pnpm run typecheck && pnpm run sample:typecheck && pnpm run scripts:typecheck && pnpm run lint:compat && pnpm run lint:dependencies && pnpm run lint:js && pnpm run format:check",
     "lint:compat": "eslint --config eslint.compat.config.mjs src",
     "lint:dependencies": "depcruise --config dependency-cruiser.config.mjs src",
-    "lint:js": "oxlint --report-unused-disable-directives --max-warnings 0 src sample && pnpm --dir test/e2e lint",
-    "lint:js:fix": "oxlint --fix src sample && pnpm --dir test/e2e lint:fix",
-    "format": "oxfmt src sample dependency-cruiser.config.mjs '!sample/dist/**' && pnpm --dir test/e2e format",
-    "format:check": "oxfmt --check src sample dependency-cruiser.config.mjs '!sample/dist/**' && pnpm --dir test/e2e format:check",
+    "lint:js": "oxlint --report-unused-disable-directives --max-warnings 0 src sample scripts && pnpm --dir test/e2e lint",
+    "lint:js:fix": "oxlint --fix src sample scripts && pnpm --dir test/e2e lint:fix",
+    "format": "oxfmt src sample scripts dependency-cruiser.config.mjs '!sample/dist/**' && pnpm --dir test/e2e format",
+    "format:check": "oxfmt --check src sample scripts dependency-cruiser.config.mjs '!sample/dist/**' && pnpm --dir test/e2e format:check",
     "typecheck": "tsc --noEmit",
     "sample": "vite --config sample/vite.config.ts",
     "sample:build": "vite build --config sample/vite.config.ts",
     "sample:preview": "vite preview --config sample/vite.config.ts",
     "sample:typecheck": "tsc --noEmit -p sample/tsconfig.json",
-    "verify": "publint",
+    "verify": "publint && vitest run --config vitest.package.config.ts",
     "snapshot": "./scripts/create_snapshot",
     "compare-snapshot": "./scripts/compare_snapshot",
-    "prepack": "pnpm run build"
+    "prepack": "pnpm run build",
+    "scripts:typecheck": "tsc --noEmit -p scripts/tsconfig.json"
   },
   "devDependencies": {
     "@custom-elements-manifest/analyzer": "^0.10.4",
diff --git a/platforms/web/package.snapshot.json b/platforms/web/package.snapshot.json
index 5c8d7138e..87f27b290 100644
--- a/platforms/web/package.snapshot.json
+++ b/platforms/web/package.snapshot.json
@@ -1,8 +1,11 @@
 [
+  "dist/chunks/register.js",
+  "dist/chunks/register.js.map",
   "dist/custom-elements.json",
   "dist/index.d.ts",
   "dist/index.js",
-  "dist/index.js.map",
+  "dist/shopify-checkout.d.ts",
+  "dist/shopify-checkout.js",
   "LICENSE",
   "package.json",
   "README.md"
diff --git a/platforms/web/sample/README.md b/platforms/web/sample/README.md
index a2e4474d0..19ba9489c 100644
--- a/platforms/web/sample/README.md
+++ b/platforms/web/sample/README.md
@@ -1,6 +1,6 @@
 # Web Component Playground
 
-A development harness for the `<shopify-checkout>` web component. It imports the same entry as published consumers (`@shopify/checkout-kit`, aliased to `../src/index.ts` in dev), registers the custom element, and logs Checkout Kit lifecycle events.
+A development harness for the `<shopify-checkout>` web component. It imports the same entry as published consumers (`@shopify/checkout-kit/shopify-checkout`, aliased to `../src/components/shopify-checkout/register.ts` in dev), registers the custom element, and logs Checkout Kit lifecycle events.
 
 ## Run locally
 
diff --git a/platforms/web/sample/main.ts b/platforms/web/sample/main.ts
index f3e7f027c..715c3b7a9 100644
--- a/platforms/web/sample/main.ts
+++ b/platforms/web/sample/main.ts
@@ -1,4 +1,4 @@
-import "@shopify/checkout-kit";
+import "@shopify/checkout-kit/shopify-checkout";
 import type { ShopifyCheckout } from "@shopify/checkout-kit";
 
 import { normalizeQuantity, normalizeStorefrontDomain, upsertCartLine } from "./cart";
diff --git a/platforms/web/sample/tsconfig.json b/platforms/web/sample/tsconfig.json
index a7fc11dfd..3b5641cb5 100644
--- a/platforms/web/sample/tsconfig.json
+++ b/platforms/web/sample/tsconfig.json
@@ -6,7 +6,8 @@
     "noEmit": true,
     "types": ["vite/client"],
     "paths": {
-      "@shopify/checkout-kit": ["../src/index.ts"]
+      "@shopify/checkout-kit": ["../src/index.ts"],
+      "@shopify/checkout-kit/shopify-checkout": ["../src/components/shopify-checkout/register.ts"]
     }
   },
   "include": ["./**/*.ts", "./**/*.d.ts"]
diff --git a/platforms/web/sample/vite.config.ts b/platforms/web/sample/vite.config.ts
index f37dd5d58..83e090db9 100644
--- a/platforms/web/sample/vite.config.ts
+++ b/platforms/web/sample/vite.config.ts
@@ -14,10 +14,13 @@ export default defineConfig({
   // Treat `sample/` as the project root so vite serves `index.html` from here.
   root: here,
   resolve: {
-    alias: {
-      // Same entry consumers use from npm (`import '@shopify/checkout-kit'`).
-      "@shopify/checkout-kit": resolve(here, "../src/index.ts"),
-    },
+    alias: [
+      {
+        find: "@shopify/checkout-kit/shopify-checkout",
+        replacement: resolve(here, "../src/components/shopify-checkout/register.ts"),
+      },
+      { find: /^@shopify\/checkout-kit$/, replacement: resolve(here, "../src/index.ts") },
+    ],
   },
   build: {
     outDir: resolve(here, "dist"),
diff --git a/platforms/web/scripts/npm-package.test.ts b/platforms/web/scripts/npm-package.test.ts
new file mode 100644
index 000000000..de85e8b40
--- /dev/null
+++ b/platforms/web/scripts/npm-package.test.ts
@@ -0,0 +1,122 @@
+// Verifies the published npm entry points after pnpm build.
+import { execFileSync } from "node:child_process";
+import { cp, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { Window } from "happy-dom";
+import { build } from "vite";
+import { afterEach, describe, expect, it } from "vitest";
+
+const packageRoot = fileURLToPath(new URL("..", import.meta.url));
+const rootEntry = "@shopify/checkout-kit";
+const componentEntry = "@shopify/checkout-kit/shopify-checkout";
+
+describe("npm component entry points", () => {
+  const fixtures: string[] = [];
+
+  afterEach(async () => {
+    await Promise.all(fixtures.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
+  });
+
+  async function createConsumer(): Promise<string> {
+    const fixture = await mkdtemp(join(tmpdir(), "checkout-kit-consumer-"));
+    fixtures.push(fixture);
+    const packageDir = join(fixture, "node_modules/@shopify/checkout-kit");
+    await mkdir(packageDir, { recursive: true });
+    await cp(join(packageRoot, "package.json"), join(packageDir, "package.json"));
+    await cp(join(packageRoot, "dist"), join(packageDir, "dist"), { recursive: true });
+    return fixture;
+  }
+
+  it.each([
+    { name: "component subpath", entries: [componentEntry] },
+    { name: "legacy root", entries: [rootEntry] },
+    { name: "component followed by root", entries: [componentEntry, rootEntry] },
+    { name: "root followed by component", entries: [rootEntry, componentEntry] },
+  ])("preserves registration after consumer bundling: $name", async ({ entries }) => {
+    const fixture = await createConsumer();
+    const entry = join(fixture, "main.js");
+    await writeFile(
+      entry,
+      entries.map((specifier) => `import ${JSON.stringify(specifier)};`).join("\n"),
+    );
+
+    const modules: string[] = [];
+    const result = await build({
+      plugins: [
+        {
+          name: "record-consumer-modules",
+          moduleParsed(module) {
+            modules.push(module.id);
+          },
+        },
+      ],
+      configFile: false,
+      root: fixture,
+      logLevel: "silent",
+      build: {
+        write: false,
+        lib: { entry, formats: ["iife"], name: "Consumer" },
+      },
+    });
+
+    const window = new Window({
+      settings: {
+        enableJavaScriptEvaluation: true,
+        suppressInsecureJavaScriptEnvironmentWarning: true,
+      },
+    });
+    try {
+      for (const bundle of [result].flat()) {
+        if (!("output" in bundle)) continue;
+        for (const output of bundle.output) {
+          if (output.type !== "chunk") continue;
+          window.eval(output.code);
+        }
+      }
+      expect(window.customElements.get("shopify-checkout")).toBeDefined();
+      const element = window.document.createElement("shopify-checkout");
+      expect(typeof (element as unknown as { open: unknown }).open).toBe("function");
+      // Component consumers must not go through the umbrella entry.
+      expect(modules.some((id) => id.endsWith("/dist/index.js"))).toBe(entries.includes(rootEntry));
+    } finally {
+      await window.happyDOM.close();
+    }
+  });
+
+  it("resolves the component import and public types in a TypeScript consumer", async () => {
+    const fixture = await createConsumer();
+    const entry = join(fixture, "main.ts");
+    await writeFile(
+      entry,
+      `
+      import '${componentEntry}';
+      import type { ShopifyCheckout } from '${rootEntry}';
+      const checkout = document.createElement('shopify-checkout') as ShopifyCheckout;
+      checkout.open();
+    `,
+    );
+    expect(() =>
+      execFileSync(
+        process.execPath,
+        [
+          fileURLToPath(import.meta.resolve("typescript/bin/tsc")),
+          "--noEmit",
+          "--strict",
+          "--noUncheckedSideEffectImports",
+          "--module",
+          "ESNext",
+          "--moduleResolution",
+          "Bundler",
+          "--target",
+          "ES2022",
+          "--skipLibCheck",
+          entry,
+        ],
+        { stdio: "pipe" },
+      ),
+    ).not.toThrow();
+  });
+});
diff --git a/platforms/web/scripts/tsconfig.json b/platforms/web/scripts/tsconfig.json
new file mode 100644
index 000000000..d93a1b379
--- /dev/null
+++ b/platforms/web/scripts/tsconfig.json
@@ -0,0 +1,10 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "isolatedDeclarations": false,
+    "declaration": false,
+    "noEmit": true,
+    "types": ["node", "vitest/globals"]
+  },
+  "include": ["./**/*.ts"]
+}
diff --git a/platforms/web/src/browser-capabilities.ts b/platforms/web/src/components/shopify-checkout/browser-capabilities.ts
similarity index 100%
rename from platforms/web/src/browser-capabilities.ts
rename to platforms/web/src/components/shopify-checkout/browser-capabilities.ts
diff --git a/platforms/web/src/checkout-events.ts b/platforms/web/src/components/shopify-checkout/checkout-events.ts
similarity index 94%
rename from platforms/web/src/checkout-events.ts
rename to platforms/web/src/components/shopify-checkout/checkout-events.ts
index da8404aa9..cbfb963aa 100644
--- a/platforms/web/src/checkout-events.ts
+++ b/platforms/web/src/components/shopify-checkout/checkout-events.ts
@@ -1,5 +1,5 @@
-import type { Checkout } from "./models/checkout";
-import type { CheckoutError } from "./models/error";
+import type { Checkout } from "../../models/checkout";
+import type { CheckoutError } from "../../models/error";
 
 export interface ShopifyCheckoutStartEventDetail {
   checkout: Checkout;
diff --git a/platforms/web/src/checkout-protocol.test.ts b/platforms/web/src/components/shopify-checkout/checkout-protocol.test.ts
similarity index 99%
rename from platforms/web/src/checkout-protocol.test.ts
rename to platforms/web/src/components/shopify-checkout/checkout-protocol.test.ts
index 78a816879..2540fdcfd 100644
--- a/platforms/web/src/checkout-protocol.test.ts
+++ b/platforms/web/src/components/shopify-checkout/checkout-protocol.test.ts
@@ -6,9 +6,9 @@ import {
 } from "@shopify/checkout-kit-protocol";
 
 import type { CheckoutProtocolMessageMap } from "./checkout.types";
-import "./checkout-web-component";
-import type { ShopifyCheckout } from "./checkout";
-import { mockTelemetry } from "./telemetry.test-helpers";
+import "./register";
+import type { ShopifyCheckout } from "./shopify-checkout";
+import { mockTelemetry } from "../../telemetry.test-helpers";
 
 const EMBED_PROTOCOL_VERSION = EmbeddedCheckoutProtocol.specVersion;
 const CHECKOUT_CHANGE_METHODS = [
diff --git a/platforms/web/src/checkout-window.test.ts b/platforms/web/src/components/shopify-checkout/checkout-window.test.ts
similarity index 99%
rename from platforms/web/src/checkout-window.test.ts
rename to platforms/web/src/components/shopify-checkout/checkout-window.test.ts
index 4f7c0125b..375de9b04 100644
--- a/platforms/web/src/checkout-window.test.ts
+++ b/platforms/web/src/components/shopify-checkout/checkout-window.test.ts
@@ -1,10 +1,10 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { EmbeddedCheckoutProtocol } from "@shopify/checkout-kit-protocol";
 
-import "./checkout-web-component";
-import { DEFAULT_POPUP_WIDTH, DEFAULT_POPUP_HEIGHT } from "./checkout";
-import type { ShopifyCheckout } from "./checkout";
-import { mockTelemetry } from "./telemetry.test-helpers";
+import "./register";
+import { DEFAULT_POPUP_WIDTH, DEFAULT_POPUP_HEIGHT } from "./shopify-checkout";
+import type { ShopifyCheckout } from "./shopify-checkout";
+import { mockTelemetry } from "../../telemetry.test-helpers";
 
 const EMBED_PROTOCOL_VERSION = EmbeddedCheckoutProtocol.specVersion;
 
diff --git a/platforms/web/src/checkout.types.ts b/platforms/web/src/components/shopify-checkout/checkout.types.ts
similarity index 97%
rename from platforms/web/src/checkout.types.ts
rename to platforms/web/src/components/shopify-checkout/checkout.types.ts
index 121e74f88..5c56bf49c 100644
--- a/platforms/web/src/checkout.types.ts
+++ b/platforms/web/src/components/shopify-checkout/checkout.types.ts
@@ -8,11 +8,11 @@ import type {
   ErrorResponse,
 } from "@shopify/checkout-kit-protocol";
 
-import type { LogLevel } from "./logger";
+import type { LogLevel } from "../../logger";
 
 export type { LogLevel };
-export type { Checkout } from "./models/checkout";
-export type { CheckoutError, CheckoutErrorCode } from "./models/error";
+export type { Checkout } from "../../models/checkout";
+export type { CheckoutError, CheckoutErrorCode } from "../../models/error";
 
 // This component should follow the custom element conventions set out here:
 // https://github.com/Shopify/ui-api-design/tree/main/codex. In particular,
diff --git a/platforms/web/src/checkout-web-component.ts b/platforms/web/src/components/shopify-checkout/register.ts
similarity index 75%
rename from platforms/web/src/checkout-web-component.ts
rename to platforms/web/src/components/shopify-checkout/register.ts
index b4d2ae357..23aca94cd 100644
--- a/platforms/web/src/checkout-web-component.ts
+++ b/platforms/web/src/components/shopify-checkout/register.ts
@@ -1,4 +1,4 @@
-import { ShopifyCheckout } from "./checkout";
+import { ShopifyCheckout } from "./shopify-checkout";
 
 declare global {
   interface HTMLElementTagNameMap {
diff --git a/platforms/web/src/checkout.css b/platforms/web/src/components/shopify-checkout/shopify-checkout.css
similarity index 100%
rename from platforms/web/src/checkout.css
rename to platforms/web/src/components/shopify-checkout/shopify-checkout.css
diff --git a/platforms/web/src/checkout.test.ts b/platforms/web/src/components/shopify-checkout/shopify-checkout.test.ts
similarity index 98%
rename from platforms/web/src/checkout.test.ts
rename to platforms/web/src/components/shopify-checkout/shopify-checkout.test.ts
index 8b0be1a6a..029ef6b89 100644
--- a/platforms/web/src/checkout.test.ts
+++ b/platforms/web/src/components/shopify-checkout/shopify-checkout.test.ts
@@ -1,16 +1,16 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { EmbeddedCheckoutProtocol } from "@shopify/checkout-kit-protocol";
 
-import { version } from "../package.json";
+import { version } from "../../../package.json";
 
-import "./checkout-web-component";
-import { CK_VERSION } from "./checkout";
+import "./register";
+import { CK_VERSION } from "./shopify-checkout";
 import {
   createTestTelemetry,
   installTestTelemetryFactory,
   mockTelemetry,
-} from "./telemetry.test-helpers";
-import { overrideTelemetryFactoryForTesting } from "./telemetry";
+} from "../../telemetry.test-helpers";
+import { overrideTelemetryFactoryForTesting } from "../../telemetry";
 
 const EMBED_PROTOCOL_VERSION = EmbeddedCheckoutProtocol.specVersion;
 
diff --git a/platforms/web/src/checkout.ts b/platforms/web/src/components/shopify-checkout/shopify-checkout.ts
similarity index 98%
rename from platforms/web/src/checkout.ts
rename to platforms/web/src/components/shopify-checkout/shopify-checkout.ts
index 4fd43e4f5..09af114ab 100644
--- a/platforms/web/src/checkout.ts
+++ b/platforms/web/src/components/shopify-checkout/shopify-checkout.ts
@@ -10,8 +10,8 @@ import {
 } from "@shopify/checkout-kit-protocol";
 
 import { getUnsupportedBrowserCapabilities, supportsShadowDOM } from "./browser-capabilities";
-import { toCheckout, checkoutComparisonKey } from "./models/checkout";
-import { toCheckoutError } from "./models/error";
+import { toCheckout, checkoutComparisonKey } from "../../models/checkout";
+import { toCheckoutError } from "../../models/error";
 import {
   ShopifyCheckoutStartEvent,
   ShopifyCheckoutUpdateEvent,
@@ -21,11 +21,15 @@ import {
   ShopifyCheckoutBlockedEvent,
   type ShopifyCheckoutEventMap,
 } from "./checkout-events";
-import stylesText from "./checkout.css?inline";
-import { Logger, coerceLogLevel } from "./logger";
-import { createTelemetry, telemetryProtocolMethod, type CheckoutKitTelemetry } from "./telemetry";
-import { createTemplate, html, safe } from "./utils";
-import { CK_VERSION } from "./version";
+import stylesText from "./shopify-checkout.css?inline";
+import { Logger, coerceLogLevel } from "../../logger";
+import {
+  createTelemetry,
+  telemetryProtocolMethod,
+  type CheckoutKitTelemetry,
+} from "../../telemetry";
+import { createTemplate, html, safe } from "../../utils";
+import { CK_VERSION } from "../../version";
 import type {
   CheckoutAttributes,
   CheckoutMethods,
@@ -41,7 +45,7 @@ import type {
 
 export const DEFAULT_POPUP_WIDTH = 600;
 export const DEFAULT_POPUP_HEIGHT = 600;
-export { CK_VERSION } from "./version";
+export { CK_VERSION } from "../../version";
 
 /**
  * Shopify-owned origins always allowed to post messages, alongside the cart
diff --git a/platforms/web/src/index.ts b/platforms/web/src/index.ts
index 1a95c2b3d..7a116f109 100644
--- a/platforms/web/src/index.ts
+++ b/platforms/web/src/index.ts
@@ -1,7 +1,8 @@
-// Registers `<shopify-checkout>` (side effect).
-import "./checkout-web-component";
+// Preserve the existing root import. New components register through their
+// own package subpaths rather than being added to this entry.
+import "./components/shopify-checkout/register";
 
-export { ShopifyCheckout } from "./checkout";
+export { ShopifyCheckout } from "./components/shopify-checkout/shopify-checkout";
 
 export {
   ShopifyCheckoutStartEvent,
@@ -10,7 +11,7 @@ export {
   ShopifyCheckoutErrorEvent,
   ShopifyCheckoutCloseEvent,
   ShopifyCheckoutBlockedEvent,
-} from "./checkout-events";
+} from "./components/shopify-checkout/checkout-events";
 
 export type {
   ShopifyCheckoutStartEventDetail,
@@ -20,7 +21,7 @@ export type {
   ShopifyCheckoutBlockedEventDetail,
   CheckoutBlockedCode,
   ShopifyCheckoutEventMap,
-} from "./checkout-events";
+} from "./components/shopify-checkout/checkout-events";
 
 export type {
   CheckoutAppearance,
@@ -30,7 +31,13 @@ export type {
   CheckoutErrorCode,
   LogLevel,
   MessageRejectedDetail,
-} from "./checkout.types";
+} from "./components/shopify-checkout/checkout.types";
 
 // Shared domain types used by the Kit-owned checkout snapshot.
-export type { Buyer, LineItem, Message, OrderConfirmation, CheckoutTotal } from "./checkout.types";
+export type {
+  Buyer,
+  LineItem,
+  Message,
+  OrderConfirmation,
+  CheckoutTotal,
+} from "./components/shopify-checkout/checkout.types";
diff --git a/platforms/web/test/e2e/README.md b/platforms/web/test/e2e/README.md
index 9b314eb34..2a70cb024 100644
--- a/platforms/web/test/e2e/README.md
+++ b/platforms/web/test/e2e/README.md
@@ -1,6 +1,6 @@
 # Web browser tests
 
-Playwright loads the built `platforms/web/dist/index.js` in Chromium and exercises
+Playwright loads the built `platforms/web/dist/shopify-checkout.js` in Chromium and exercises
 the real custom element, popup, and cross-origin `postMessage` exchange. A routed
 HTTPS checkout fixture supplies synthetic protocol messages; telemetry is disabled
 and unexpected external requests are blocked and fail the test. No storefront,
diff --git a/platforms/web/test/e2e/fixtures/host.html b/platforms/web/test/e2e/fixtures/host.html
index edd98ef67..4912e18de 100644
--- a/platforms/web/test/e2e/fixtures/host.html
+++ b/platforms/web/test/e2e/fixtures/host.html
@@ -8,7 +8,7 @@
     <shopify-checkout id="checkout" target="popup" telemetry="false"></shopify-checkout>
     <button id="buy" type="button">Buy</button>
     <script type="module">
-      import "/dist/index.js";
+      import "/dist/shopify-checkout.js";
 
       const checkout = document.getElementById("checkout");
       window.checkoutEvents = [];
diff --git a/platforms/web/test/e2e/server.mjs b/platforms/web/test/e2e/server.mjs
index 638035cc6..17f62742a 100644
--- a/platforms/web/test/e2e/server.mjs
+++ b/platforms/web/test/e2e/server.mjs
@@ -1,15 +1,17 @@
 import { createServer } from "node:http";
-import { access, readFile } from "node:fs/promises";
+import { access, readFile, readdir } from "node:fs/promises";
 
-const bundle = new URL("../../dist/index.js", import.meta.url);
+const dist = new URL("../../dist/", import.meta.url);
+const bundle = new URL("shopify-checkout.js", dist);
 await access(bundle).catch(() => {
   throw new Error("Built web component not found. Run `dev web build` first.");
 });
 
-const files = new Map([
-  ["/", [new URL("./fixtures/host.html", import.meta.url), "text/html"]],
-  ["/dist/index.js", [bundle, "text/javascript"]],
-]);
+const files = new Map([["/", [new URL("./fixtures/host.html", import.meta.url), "text/html"]]]);
+// Serve only built JavaScript files, including shared entry-point chunks.
+for (const path of await readdir(dist, { recursive: true })) {
+  if (path.endsWith(".js")) files.set(`/dist/${path}`, [new URL(path, dist), "text/javascript"]);
+}
 
 createServer(async (request, response) => {
   const path = new URL(request.url ?? "/", "http://localhost").pathname;
diff --git a/platforms/web/vite.config.ts b/platforms/web/vite.config.ts
index 9ad331720..b4a31967e 100644
--- a/platforms/web/vite.config.ts
+++ b/platforms/web/vite.config.ts
@@ -46,14 +46,18 @@ export default defineConfig({
     emptyOutDir: true,
     outDir: fromRoot('dist'),
     lib: {
-      entry: fromRoot('src/index.ts'),
+      entry: {
+        index: fromRoot('src/index.ts'),
+        'shopify-checkout': fromRoot('src/components/shopify-checkout/register.ts'),
+      },
       formats: ['es'],
-      fileName: () => 'index.js',
+      fileName: (_, entryName) => `${entryName}.js`,
     },
     rollupOptions: {
-      // Zero runtime deps — bundle everything reachable from src/index.ts.
+      // Zero runtime dependencies — bundle the npm entries and their dependencies.
       external: [],
       output: {
+        chunkFileNames: 'chunks/[name].js',
         minify: {
           compress: true,
           mangle: true,
@@ -76,6 +80,8 @@ export default defineConfig({
     globals: true,
     setupFiles: ['./vitest.setup.ts'],
     include: ['src/**/*.test.ts', 'sample/**/*.test.ts', 'scripts/**/*.test.ts'],
+    // Package tests run against the build via pnpm verify.
+    exclude: ['**/node_modules/**', 'scripts/*package.test.ts'],
     coverage: {
       provider: 'v8',
       reporter: ['text', 'json-summary', 'html', 'lcov'],
diff --git a/platforms/web/vitest.package.config.ts b/platforms/web/vitest.package.config.ts
new file mode 100644
index 000000000..34eeb50a5
--- /dev/null
+++ b/platforms/web/vitest.package.config.ts
@@ -0,0 +1,11 @@
+import {defineConfig} from 'vitest/config';
+
+// Verifies dist/. Kept out of the default vitest config
+// so `pnpm test` does not depend on a prior build; `pnpm verify` runs it.
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['scripts/*package.test.ts'],
+    testTimeout: 60_000,
+  },
+});
diff --git a/scripts/test/changed_file_filters_test.rb b/scripts/test/changed_file_filters_test.rb
index 1d95b462a..131c12bb2 100644
--- a/scripts/test/changed_file_filters_test.rb
+++ b/scripts/test/changed_file_filters_test.rb
@@ -18,7 +18,7 @@ def test_matches_file_inside_platform_directory
   def test_matches_platform_and_telemetry_paths_independently
     {
       "web" => [
-        "platforms/web/src/checkout.ts",
+        "platforms/web/src/components/shopify-checkout/shopify-checkout.ts",
         "telemetry/languages/typescript/src/types.ts",
         "telemetry/contract/schema.json"
       ],

From 13b8374bb30f5a2cbc9ba7469be17404891dc87e Mon Sep 17 00:00:00 2001
From: Daniel Kift <daniel.kift@shopify.com>
Date: Thu, 8 Oct 2026 15:23:13 +0100
Subject: [PATCH 2/3] Type the tag from the component entry and exclude all
 type-only modules

- The component entry's declarations now load the root declarations, so
  `import "@shopify/checkout-kit/shopify-checkout"` alone types
  document.createElement("shopify-checkout") as ShopifyCheckout. The
  TypeScript consumer test no longer casts and covers both import styles.
- Exclude every `.types.ts` module from the reachability rule rather than
  only checkout.types.ts (review feedback).
---
 platforms/web/dependency-cruiser.config.mjs |  3 +-
 platforms/web/scripts/npm-package.test.ts   | 31 ++++++++++++++-------
 platforms/web/vite.config.ts                |  3 ++
 3 files changed, 26 insertions(+), 11 deletions(-)

diff --git a/platforms/web/dependency-cruiser.config.mjs b/platforms/web/dependency-cruiser.config.mjs
index 00f35613f..3763c1ebf 100644
--- a/platforms/web/dependency-cruiser.config.mjs
+++ b/platforms/web/dependency-cruiser.config.mjs
@@ -21,7 +21,8 @@ export default {
         pathNot: [
           "(^|/)node_modules/",
           "^package\\.json$",
-          "^src/components/shopify-checkout/checkout\\.types\\.ts$",
+          // Type-only modules are erased at compile time, so nothing reaches them at runtime.
+          "\\.types\\.ts$",
           "\\.d\\.ts$",
           "\\.test\\.ts$",
           "\\.test-helpers\\.ts$",
diff --git a/platforms/web/scripts/npm-package.test.ts b/platforms/web/scripts/npm-package.test.ts
index de85e8b40..3cff2d888 100644
--- a/platforms/web/scripts/npm-package.test.ts
+++ b/platforms/web/scripts/npm-package.test.ts
@@ -86,18 +86,29 @@ describe("npm component entry points", () => {
     }
   });
 
-  it("resolves the component import and public types in a TypeScript consumer", async () => {
+  it.each([
+    {
+      name: "with public types from the root",
+      source: `
+        import '${componentEntry}';
+        import type { ShopifyCheckout } from '${rootEntry}';
+        const checkout: ShopifyCheckout = document.createElement('shopify-checkout');
+        checkout.open();
+      `,
+    },
+    {
+      // The tag-name typing must arrive with the component import alone.
+      name: "from the component import alone",
+      source: `
+        import '${componentEntry}';
+        document.createElement('shopify-checkout').open();
+        document.querySelector('shopify-checkout')?.close();
+      `,
+    },
+  ])("types the shopify-checkout tag in a TypeScript consumer $name", async ({ source }) => {
     const fixture = await createConsumer();
     const entry = join(fixture, "main.ts");
-    await writeFile(
-      entry,
-      `
-      import '${componentEntry}';
-      import type { ShopifyCheckout } from '${rootEntry}';
-      const checkout = document.createElement('shopify-checkout') as ShopifyCheckout;
-      checkout.open();
-    `,
-    );
+    await writeFile(entry, source);
     expect(() =>
       execFileSync(
         process.execPath,
diff --git a/platforms/web/vite.config.ts b/platforms/web/vite.config.ts
index b4a31967e..5b84590c4 100644
--- a/platforms/web/vite.config.ts
+++ b/platforms/web/vite.config.ts
@@ -36,6 +36,9 @@ export default defineConfig({
       async afterBuild() {
         const entry = fromRoot('dist/index.d.ts');
         await writeFile(entry, appendTagNameMap(await readFile(entry, 'utf8'), tagNames.tags));
+        // Component entries have no exports of their own and roll up to `export {}`. Load the root
+        // declarations so a component import alone brings the tag-name typing.
+        await writeFile(fromRoot('dist/shopify-checkout.d.ts'), 'import "./index.js";\n\nexport {};\n');
       },
     }),
   ],

From 3d2f45d11a0f365a230038a5e76bd51b943bbbe6 Mon Sep 17 00:00:00 2001
From: Daniel Kift <daniel.kift@shopify.com>
Date: Thu, 8 Oct 2026 17:18:53 +0100
Subject: [PATCH 3/3] Make the root import side-effect free and add
 ShopifyCheckout.register()

Follow the common web component package pattern (Shoelace/Web Awesome,
Material Web, Spectrum): component imports register, and the package
root only exports classes, events, and types.

- `import "@shopify/checkout-kit"` no longer registers
  <shopify-checkout>. This is a breaking change for consumers relying on
  the root import to register; the README calls it out.
- Add `ShopifyCheckout.register(name?, registry?)`. The default name
  registers the class itself; each custom name gets its own subclass,
  since a registry accepts a constructor only once. Registering a name
  the class already owns returns that class; a name owned by another
  element throws.
- The component entry registers through `register()` and leaves an
  existing <shopify-checkout> in place, so loading Checkout Kit twice
  (bundle plus CDN loader) doesn't fail.
- `sideEffects` now lists only the component entry. The shared chunk is
  pure and is renamed from chunks/register.js to
  chunks/shopify-checkout.js.
- Keep the custom elements manifest's tag-to-class definition: the
  analyzer can't follow `register()`, so a manifest plugin recreates it
  from the class's `@tagname`.
- dependency-cruiser treats component entries as entry points.
- Package tests cover every import combination, including custom names
  and an existing <shopify-checkout> on the page.
---
 platforms/web/README.md                       |  65 ++++++++---
 .../web/custom-elements-manifest.config.mjs   |  44 ++++++++
 platforms/web/dependency-cruiser.config.mjs   |   6 +-
 platforms/web/package.json                    |   5 +-
 platforms/web/package.snapshot.json           |   5 +-
 platforms/web/scripts/npm-package.test.ts     | 104 ++++++++++++++----
 .../shopify-checkout/register.test.ts         |  53 +++++++++
 .../components/shopify-checkout/register.ts   |   9 +-
 .../shopify-checkout/shopify-checkout.ts      |  32 ++++++
 platforms/web/src/index.test.ts               |   4 +-
 platforms/web/src/index.ts                    |   6 +-
 11 files changed, 281 insertions(+), 52 deletions(-)
 create mode 100644 platforms/web/src/components/shopify-checkout/register.test.ts

diff --git a/platforms/web/README.md b/platforms/web/README.md
index d2f2e15b9..d9befb4fe 100644
--- a/platforms/web/README.md
+++ b/platforms/web/README.md
@@ -94,9 +94,15 @@ import '@shopify/checkout-kit/shopify-checkout';
 ```
 
 Components use separate entry points within the same npm package. Import only
-the components you need. The existing root import (`@shopify/checkout-kit`)
-continues to register `<shopify-checkout>` for compatibility; it will not
-automatically register additional components.
+the components you need. The package root (`@shopify/checkout-kit`) exports the
+classes, events, and types without registering anything; see
+[manual registration](#manual-registration-and-custom-tag-names).
+
+> [!IMPORTANT]
+> `import '@shopify/checkout-kit'` no longer registers `<shopify-checkout>`.
+> Import `@shopify/checkout-kit/shopify-checkout` instead, or call
+> `ShopifyCheckout.register()`. Without either, `<shopify-checkout>` elements
+> stay unregistered and checkout won't open.
 
 Then render the element anywhere in your HTML and call `open()` to present
 checkout:
@@ -149,18 +155,47 @@ checkout.open();
 checkout.close();
 ```
 
-The `ShopifyCheckout` class is also exported directly when you need the
-constructor. This existing root import also registers `<shopify-checkout>`
-with `customElements`:
+## Manual registration and custom tag names
+
+The package root exports the `ShopifyCheckout` class without registering it.
+Call `ShopifyCheckout.register()` to register `<shopify-checkout>` yourself, for
+example to control when registration happens:
 
 ```ts
 import {ShopifyCheckout} from '@shopify/checkout-kit';
 
+ShopifyCheckout.register();
+
 const checkout = new ShopifyCheckout();
 checkout.src = 'https://your-store.myshopify.com/checkouts/cn/abc123';
 document.body.append(checkout);
 ```
 
+Pass a tag name to register the element under a different name. `register()`
+returns the registered class: each custom name gets its own subclass of
+`ShopifyCheckout`, because the browser accepts each constructor only once.
+
+```ts
+import {ShopifyCheckout} from '@shopify/checkout-kit';
+
+const AcmeCheckout = ShopifyCheckout.register('acme-checkout');
+
+const checkout = document.querySelector('acme-checkout') as InstanceType<typeof AcmeCheckout>;
+checkout.open();
+```
+
+- Calling `register()` again for a name this class already registered returns
+  the existing class, so it's safe to call more than once.
+- It throws if another element already uses the name, including a separate copy
+  of Checkout Kit. The component entry instead leaves an existing
+  `<shopify-checkout>` in place, so loading Checkout Kit twice doesn't fail.
+- Importing `@shopify/checkout-kit/shopify-checkout` registers
+  `<shopify-checkout>`. It also works alongside custom names: the page then has
+  both tags.
+- TypeScript only knows the default tag: `document.createElement('shopify-checkout')`
+  returns a `ShopifyCheckout`. Custom tags return a plain `HTMLElement`, so use
+  the class `register()` returns or a cast.
+
 ## Usage with other frameworks
 
 ### React
@@ -244,11 +279,10 @@ declare module 'react' {
 > the `react` module.
 
 > [!NOTE]
-> The `import '@shopify/checkout-kit/shopify-checkout'` side effect registers the element with
-> `customElements` and touches browser-only globals, so it must run on the
-> client. In server-rendered frameworks (Next.js, Remix), keep the import and
-> the component in a client component — e.g. add `'use client'` to the top of
-> the file.
+> Both `import '@shopify/checkout-kit/shopify-checkout'` and the package root
+> touch browser-only globals when they load, so they must run on the client. In
+> server-rendered frameworks (Next.js, Remix), keep the import and the component
+> in a client component — e.g. add `'use client'` to the top of the file.
 
 ## Usage with the Shopify Storefront API
 
@@ -630,6 +664,9 @@ element. Import files directly rather than adding component barrel files.
 
 New components such as `accelerated-checkouts`, `universal-checkout`, and
 `shop-wallet` should follow the same layout when added. Shared models and helpers
-stay outside component directories. `src/index.ts` remains the public npm entry
-for `@shopify/checkout-kit`. Expose each component through its own package subpath
-pointing to `register.ts`; do not add every component registration to the root entry.
+stay outside component directories. `src/index.ts` is the public npm entry
+for `@shopify/checkout-kit`: it exports classes, events, and types, and must not
+register elements. Expose each component through its own package subpath
+pointing to `register.ts`, which registers the element through the class's static
+`register()`. Add `@tagname` to the class so the custom elements manifest maps the
+tag to it, and list the component entry in `sideEffects`.
diff --git a/platforms/web/custom-elements-manifest.config.mjs b/platforms/web/custom-elements-manifest.config.mjs
index b20be988a..a57157a67 100644
--- a/platforms/web/custom-elements-manifest.config.mjs
+++ b/platforms/web/custom-elements-manifest.config.mjs
@@ -3,9 +3,53 @@
 // Storybook consume to provide HTML attribute autocompletion and docs.
 //
 // Docs: https://custom-elements-manifest.open-wc.org/analyzer/getting-started/
+
+// Each component's `register.ts` defines its element through the class's static
+// `register()` rather than a literal `customElements.define()` call, which the
+// analyzer can't follow. Re-create the definition export from the component's
+// `@tagname`, so tools still map the tag to its class.
+function componentDefinitions() {
+  return {
+    name: 'checkout-kit:component-definitions',
+    packageLinkPhase({customElementsManifest}) {
+      const {modules} = customElementsManifest;
+      for (const module of modules) {
+        const component = module.path.match(/^src\/components\/([^/]+)\/register\.ts$/)?.[1];
+        if (!component) continue;
+        const path = `src/components/${component}/${component}.ts`;
+        const element = modules
+          .find((candidate) => candidate.path === path)
+          ?.declarations?.find((declaration) => declaration.customElement && declaration.tagName);
+        if (!element) {
+          throw new Error(`${module.path}: expected a custom element class with @tagname in ${path}`);
+        }
+        module.exports = [
+          ...(module.exports ?? []).filter(({kind}) => kind !== 'custom-element-definition'),
+          {
+            kind: 'custom-element-definition',
+            name: element.tagName,
+            declaration: {name: element.name, module: `/${path.replace(/\.ts$/, '')}`},
+          },
+        ];
+      }
+      // TypeScript `this` parameters are type annotations, not arguments.
+      for (const module of modules) {
+        for (const declaration of module.declarations ?? []) {
+          for (const member of declaration.members ?? []) {
+            if (member.parameters) {
+              member.parameters = member.parameters.filter(({name}) => name !== 'this');
+            }
+          }
+        }
+      }
+    },
+  };
+}
+
 export default {
   globs: ['src/**/*.ts'],
   exclude: ['src/**/*.test.ts'],
   outdir: 'dist',
   packagejson: true,
+  plugins: [componentDefinitions()],
 };
diff --git a/platforms/web/dependency-cruiser.config.mjs b/platforms/web/dependency-cruiser.config.mjs
index 3763c1ebf..c96fc923d 100644
--- a/platforms/web/dependency-cruiser.config.mjs
+++ b/platforms/web/dependency-cruiser.config.mjs
@@ -13,14 +13,16 @@ export default {
     {
       name: "all-runtime-source-is-reachable-from-public-entrypoint",
       comment:
-        "Production source must be reachable from src/index.ts so it is either shipped or deleted.",
+        "Production source must be reachable from a package entry (src/index.ts or a component's register.ts) so it is either shipped or deleted.",
       severity: "error",
-      from: { path: "^src/index\\.ts$" },
+      from: { path: "^src/(index|components/[^/]+/register)\\.ts$" },
       to: {
         reachable: false,
         pathNot: [
           "(^|/)node_modules/",
           "^package\\.json$",
+          // The entries themselves; a module doesn't count as reachable from itself.
+          "^src/(index|components/[^/]+/register)\\.ts$",
           // Type-only modules are erased at compile time, so nothing reaches them at runtime.
           "\\.types\\.ts$",
           "\\.d\\.ts$",
diff --git a/platforms/web/package.json b/platforms/web/package.json
index b6bb556e0..c2d745fac 100644
--- a/platforms/web/package.json
+++ b/platforms/web/package.json
@@ -37,11 +37,8 @@
     "./package.json": "./package.json"
   },
   "sideEffects": [
-    "./src/index.ts",
     "./src/components/shopify-checkout/register.ts",
-    "./dist/index.js",
-    "./dist/shopify-checkout.js",
-    "./dist/chunks/*.js"
+    "./dist/shopify-checkout.js"
   ],
   "files": [
     "LICENSE",
diff --git a/platforms/web/package.snapshot.json b/platforms/web/package.snapshot.json
index 87f27b290..eec8efa29 100644
--- a/platforms/web/package.snapshot.json
+++ b/platforms/web/package.snapshot.json
@@ -1,11 +1,12 @@
 [
-  "dist/chunks/register.js",
-  "dist/chunks/register.js.map",
+  "dist/chunks/shopify-checkout.js",
+  "dist/chunks/shopify-checkout.js.map",
   "dist/custom-elements.json",
   "dist/index.d.ts",
   "dist/index.js",
   "dist/shopify-checkout.d.ts",
   "dist/shopify-checkout.js",
+  "dist/shopify-checkout.js.map",
   "LICENSE",
   "package.json",
   "README.md"
diff --git a/platforms/web/scripts/npm-package.test.ts b/platforms/web/scripts/npm-package.test.ts
index 3cff2d888..c77642be8 100644
--- a/platforms/web/scripts/npm-package.test.ts
+++ b/platforms/web/scripts/npm-package.test.ts
@@ -30,18 +30,82 @@ describe("npm component entry points", () => {
     return fixture;
   }
 
+  const importRoot = `import { ShopifyCheckout } from ${JSON.stringify(rootEntry)};`;
+  const importComponent = `import ${JSON.stringify(componentEntry)};`;
+
   it.each([
-    { name: "component subpath", entries: [componentEntry] },
-    { name: "legacy root", entries: [rootEntry] },
-    { name: "component followed by root", entries: [componentEntry, rootEntry] },
-    { name: "root followed by component", entries: [rootEntry, componentEntry] },
-  ])("preserves registration after consumer bundling: $name", async ({ entries }) => {
+    {
+      name: "component import",
+      source: importComponent,
+      registered: ["shopify-checkout"],
+      root: false,
+    },
+    {
+      name: "root import alone registers nothing",
+      source: `${importRoot}\nglobalThis.checkoutClass = ShopifyCheckout;`,
+      registered: [],
+      root: true,
+    },
+    {
+      name: "root import then register()",
+      source: `${importRoot}\nShopifyCheckout.register();`,
+      registered: ["shopify-checkout"],
+      root: true,
+    },
+    {
+      name: "root import then a custom tag name",
+      source: `${importRoot}\nShopifyCheckout.register("acme-checkout");`,
+      registered: ["acme-checkout"],
+      root: true,
+    },
+    {
+      name: "component import then a custom tag name",
+      source: `${importComponent}\n${importRoot}\nShopifyCheckout.register("acme-checkout");`,
+      registered: ["shopify-checkout", "acme-checkout"],
+      root: true,
+    },
+    {
+      name: "root import followed by component import",
+      source: `${importRoot}\n${importComponent}\nShopifyCheckout.register();`,
+      registered: ["shopify-checkout"],
+      root: true,
+    },
+  ])("registers after consumer bundling: $name", async ({ source, registered, root }) => {
+    const { window, modules } = await bundleAndRun(source);
+    try {
+      const tags = ["shopify-checkout", "acme-checkout"];
+      expect(
+        Object.fromEntries(tags.map((tag) => [tag, Boolean(window.customElements.get(tag))])),
+      ).toEqual(Object.fromEntries(tags.map((tag) => [tag, registered.includes(tag)])));
+      for (const tag of registered) {
+        const element = window.document.createElement(tag);
+        expect(typeof (element as unknown as { open: unknown }).open).toBe("function");
+      }
+      // Component consumers must not go through the umbrella entry.
+      expect(modules.some((id) => id.endsWith("/dist/index.js"))).toBe(root);
+    } finally {
+      await window.happyDOM.close();
+    }
+  });
+
+  it("leaves an existing <shopify-checkout> in place when the component entry loads", async () => {
+    // For example a second copy of Checkout Kit, such as the CDN loader alongside a bundle.
+    const { window } = await bundleAndRun(
+      importComponent,
+      'customElements.define("shopify-checkout", class Existing extends HTMLElement {});',
+    );
+    try {
+      expect(window.customElements.get("shopify-checkout")?.name).toBe("Existing");
+    } finally {
+      await window.happyDOM.close();
+    }
+  });
+
+  // Bundles `source` as a consumer would, then evaluates it in a fresh window after `prelude`.
+  async function bundleAndRun(source: string, prelude = "") {
     const fixture = await createConsumer();
     const entry = join(fixture, "main.js");
-    await writeFile(
-      entry,
-      entries.map((specifier) => `import ${JSON.stringify(specifier)};`).join("\n"),
-    );
+    await writeFile(entry, source);
 
     const modules: string[] = [];
     const result = await build({
@@ -68,23 +132,15 @@ describe("npm component entry points", () => {
         suppressInsecureJavaScriptEnvironmentWarning: true,
       },
     });
-    try {
-      for (const bundle of [result].flat()) {
-        if (!("output" in bundle)) continue;
-        for (const output of bundle.output) {
-          if (output.type !== "chunk") continue;
-          window.eval(output.code);
-        }
+    if (prelude) window.eval(prelude);
+    for (const bundle of [result].flat()) {
+      if (!("output" in bundle)) continue;
+      for (const output of bundle.output) {
+        if (output.type === "chunk") window.eval(output.code);
       }
-      expect(window.customElements.get("shopify-checkout")).toBeDefined();
-      const element = window.document.createElement("shopify-checkout");
-      expect(typeof (element as unknown as { open: unknown }).open).toBe("function");
-      // Component consumers must not go through the umbrella entry.
-      expect(modules.some((id) => id.endsWith("/dist/index.js"))).toBe(entries.includes(rootEntry));
-    } finally {
-      await window.happyDOM.close();
     }
-  });
+    return { window, modules };
+  }
 
   it.each([
     {
diff --git a/platforms/web/src/components/shopify-checkout/register.test.ts b/platforms/web/src/components/shopify-checkout/register.test.ts
new file mode 100644
index 000000000..91951d0ad
--- /dev/null
+++ b/platforms/web/src/components/shopify-checkout/register.test.ts
@@ -0,0 +1,53 @@
+import { describe, expect, it, vi } from "vitest";
+
+import "./register";
+import { ShopifyCheckout } from "./shopify-checkout";
+
+describe("ShopifyCheckout.register", () => {
+  it("registers the class itself as <shopify-checkout> from the component entry", () => {
+    expect(customElements.get("shopify-checkout")).toBe(ShopifyCheckout);
+    expect(document.createElement("shopify-checkout")).toBeInstanceOf(ShopifyCheckout);
+  });
+
+  it("returns the existing class when the name is already registered by it", () => {
+    expect(ShopifyCheckout.register()).toBe(ShopifyCheckout);
+  });
+
+  it("defines a subclass for a custom tag name, once", () => {
+    const Custom = ShopifyCheckout.register("custom-checkout");
+
+    expect(Custom).not.toBe(ShopifyCheckout);
+    expect(Custom.prototype).toBeInstanceOf(ShopifyCheckout);
+    expect(customElements.get("custom-checkout")).toBe(Custom);
+    const element = document.createElement("custom-checkout");
+    expect(element).toBeInstanceOf(ShopifyCheckout);
+    expect(typeof (element as ShopifyCheckout).open).toBe("function");
+    expect(ShopifyCheckout.register("custom-checkout")).toBe(Custom);
+  });
+
+  it("registers subclasses under their own names", () => {
+    class BrandedCheckout extends ShopifyCheckout {}
+
+    const Branded = BrandedCheckout.register("branded-checkout");
+
+    expect(Branded.prototype).toBeInstanceOf(BrandedCheckout);
+    expect(document.createElement("branded-checkout")).toBeInstanceOf(BrandedCheckout);
+    expect(BrandedCheckout.register("branded-checkout")).toBe(Branded);
+  });
+
+  it("throws when another element already uses the name", () => {
+    customElements.define("foreign-checkout", class extends HTMLElement {});
+
+    expect(() => ShopifyCheckout.register("foreign-checkout")).toThrow(
+      "Cannot register <foreign-checkout>: another element already uses that name.",
+    );
+  });
+
+  it("defines the element in the given registry", () => {
+    const define = vi.fn();
+    const registry = { get: () => undefined, define } as unknown as CustomElementRegistry;
+
+    expect(ShopifyCheckout.register(undefined, registry)).toBe(ShopifyCheckout);
+    expect(define).toHaveBeenCalledWith("shopify-checkout", ShopifyCheckout);
+  });
+});
diff --git a/platforms/web/src/components/shopify-checkout/register.ts b/platforms/web/src/components/shopify-checkout/register.ts
index 23aca94cd..4174d4c7c 100644
--- a/platforms/web/src/components/shopify-checkout/register.ts
+++ b/platforms/web/src/components/shopify-checkout/register.ts
@@ -1,3 +1,5 @@
+// Entry point for `@shopify/checkout-kit/shopify-checkout`: importing it registers
+// `<shopify-checkout>`. The package root exports the class without registering it.
 import { ShopifyCheckout } from "./shopify-checkout";
 
 declare global {
@@ -6,4 +8,9 @@ declare global {
   }
 }
 
-customElements.define("shopify-checkout", ShopifyCheckout);
+// A page may load Checkout Kit more than once (an npm bundle plus the CDN loader,
+// or two copies of a bundle). Leave an existing <shopify-checkout> in place rather
+// than failing the import.
+if (customElements.get("shopify-checkout") === undefined) {
+  ShopifyCheckout.register();
+}
diff --git a/platforms/web/src/components/shopify-checkout/shopify-checkout.ts b/platforms/web/src/components/shopify-checkout/shopify-checkout.ts
index 09af114ab..b27c5ada1 100644
--- a/platforms/web/src/components/shopify-checkout/shopify-checkout.ts
+++ b/platforms/web/src/components/shopify-checkout/shopify-checkout.ts
@@ -203,6 +203,8 @@ const SHADOW_TEMPLATE = createTemplate(html`
  * document.body.append(checkout);
  * checkout.open();
  * ```
+ *
+ * @tagname shopify-checkout
  */
 export class ShopifyCheckout
   extends HTMLElement
@@ -210,6 +212,36 @@ export class ShopifyCheckout
 {
   static observedAttributes = ["src", "target", "appearance", "telemetry"] as const;
 
+  /**
+   * Registers the element and returns the class registered for `name`.
+   *
+   * `import "@shopify/checkout-kit/shopify-checkout"` registers `<shopify-checkout>` for you.
+   * Call this when importing from `@shopify/checkout-kit`, which registers nothing, or to use
+   * a custom tag name. A registry accepts each constructor only once, so every custom name gets
+   * its own subclass.
+   *
+   * Registering a name this class (or a subclass) already owns returns that class.
+   *
+   * @param name - The tag name. Defaults to `shopify-checkout`.
+   * @param registry - The registry to define the element in. Defaults to `customElements`.
+   * @throws {Error} If another element already owns `name`.
+   */
+  static register<T extends typeof ShopifyCheckout>(
+    this: T,
+    name: string = "shopify-checkout",
+    registry: CustomElementRegistry = customElements,
+  ): T {
+    const existing = registry.get(name);
+    if (existing !== undefined) {
+      if (existing === this || existing.prototype instanceof this) return existing as T;
+      throw new Error(`Cannot register <${name}>: another element already uses that name.`);
+    }
+    const element =
+      name === "shopify-checkout" ? this : class extends (this as typeof ShopifyCheckout) {};
+    registry.define(name, element);
+    return element as T;
+  }
+
   constructor() {
     super();
 
diff --git a/platforms/web/src/index.test.ts b/platforms/web/src/index.test.ts
index fba4ba40a..299d0d3d4 100644
--- a/platforms/web/src/index.test.ts
+++ b/platforms/web/src/index.test.ts
@@ -23,7 +23,7 @@ describe("@shopify/checkout-kit public entry", () => {
     }
   });
 
-  it("registers <shopify-checkout> as a side effect of importing the entry", () => {
-    expect(customElements.get("shopify-checkout")).toBe(pkg.ShopifyCheckout);
+  it("does not register any element when imported", () => {
+    expect(customElements.get("shopify-checkout")).toBeUndefined();
   });
 });
diff --git a/platforms/web/src/index.ts b/platforms/web/src/index.ts
index 7a116f109..f6334ccb7 100644
--- a/platforms/web/src/index.ts
+++ b/platforms/web/src/index.ts
@@ -1,6 +1,6 @@
-// Preserve the existing root import. New components register through their
-// own package subpaths rather than being added to this entry.
-import "./components/shopify-checkout/register";
+// The package root has no side effects: it exports classes, events, and types.
+// Register elements by importing a component entry such as
+// `@shopify/checkout-kit/shopify-checkout`, or by calling `ShopifyCheckout.register()`.
 
 export { ShopifyCheckout } from "./components/shopify-checkout/shopify-checkout";