Shopify · westeezy · May 14, 2026 · May 14, 2026
@@ -26,5 +26,15 @@
     "dist/**",
     "coverage/**",
     "node_modules/**"
+  ],
+  "overrides": [
+    {
+      "files": ["**/*.test.ts"],
+      "rules": {
+        "typescript/no-non-null-assertion": "off",
+        "vitest/require-mock-type-parameters": "off",
+        "eslint/no-underscore-dangle": "off"
+      }
+    }
   ]
 }
@@ -32,7 +32,11 @@
     "./custom-elements.json": "./dist/custom-elements.json",
     "./package.json": "./package.json"
   },
-  "sideEffects": false,
+  "sideEffects": [
+    "./src/index.ts",
+    "./src/checkout-web-component.ts",
+    "./dist/index.js"
+  ],
   "files": [
     "LICENSE",
     "README.md",

@@ -1,8 +1,9 @@
 # Web Component Playground
 
-A development harness for the `<shopify-checkout>` web component. Renders the
-component with adjustable options and logs all dispatched `checkout:*` events
-in real time.
+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 `ec:*` and
+`checkout:close` events.
 
 ## Run locally
 
@@ -13,43 +14,22 @@ pnpm sample
 
 Vite serves at `http://localhost:5173`. The page has three panels:
 
-- **Options** — form for setting the component's attributes (`src`,
-  `target`) plus a small panel of manual method
-  buttons (`open()`, `close()`, `focus()`) for ad-hoc debugging.
-- **Demo Storefront** — a mocked merchant product card with a **Buy now**
-  button that calls `checkout.open()`. The button is disabled until you
-  enter a checkout URL in the Options panel. Below the card, a collapsible
-  readout shows the component's read-only state (`cart`, `locale`,
-  `orderConfirmation`, `error`, `sessionId`).
-- **Events** — a chronological log of every `checkout:*` event the component
-  dispatches, with a snapshot of component state at the moment the event
-  fired. Respondable events are tagged with a badge.
-
-The `<shopify-checkout>` element is appended to `<body>` rather than placed
-inside the storefront panel — for `popup` and `auto` targets, the element
-has no visible footprint of its own; only its internal dialog scrim appears
-when `open()` is called. `target="inline"` is intentionally not supported
-in the v1 of the component.
-
-## Status
-
-The `<shopify-checkout>` component implementation has not yet landed in
-`../src`. Until it does, the element renders as an unknown HTML element and
-dispatches no events — the playground is wired up against the component's
-eventual API surface but is **non-functional at runtime**.
-
-The forward-looking API surface is declared in [`./types.d.ts`](./types.d.ts).
-Delete that file once `@shopify/checkout-kit` exports the real `ShopifyCheckout`
-types from `../src`.
+- **Options** — form for `src`, `target` (`auto` | `popup`), and `debug`,
+  plus buttons for `open()`, `close()`, and `focus()`.
+- **Demo Storefront** — a mocked product card with **Buy now** calling
+  `checkout.open()`. The button stays disabled until a checkout URL is set.
+  The collapsible readout shows `checkout`, `error`, `target`, and `debug`.
+- **Events** — log of dispatched events with a JSON snapshot of state at fire
+  time.
+
+The element is mounted on `<body>`. For `popup` / `auto`, the visible UI is
+mostly the overlay scrim while checkout is open in a separate window or tab.
 
 ## Build
 
 ```bash
 pnpm sample:build      # outputs to sample/dist/
 ```
 
-CI runs this on every PR (see `.github/workflows/web.yml`) so the sample stays
-buildable as the package evolves.
-
-The sample is **not** published to npm — it's excluded by the `files`
-allowlist in `platforms/web/package.json`.
+CI runs this on every PR (see `.github/workflows/web.yml`). The sample is not
+published to npm (`files` allowlist in `platforms/web/package.json`).
@@ -13,8 +13,9 @@ <h1>Checkout Kit</h1>
         <p class="subtitle">Web Component Playground</p>
       </div>
       <p class="status" role="status">
-        Component not yet implemented in <code>../src</code> — clicking
-        <strong>Buy&nbsp;now</strong> is a no-op until the element is registered.
+        Loads the real <code>&lt;shopify-checkout&gt;</code> from
+        <code>@shopify/checkout-kit</code> (dev alias). Use a valid checkout URL to try
+        <strong>Buy&nbsp;now</strong>.
       </p>
     </header>
 
@@ -36,11 +37,16 @@ <h2 id="options-heading">Options</h2>
           <label>
             <span>target</span>
             <select name="target">
+              <option value="popup" selected>popup (window)</option>
               <option value="auto">auto (new tab)</option>
-              <option value="popup">popup (window)</option>
             </select>
           </label>
 
+          <label class="checkbox">
+            <input type="checkbox" name="debug" />
+            <span>debug</span>
+          </label>
+
           <fieldset>
             <legend>Methods</legend>
             <div class="button-row">
@@ -108,16 +114,14 @@ <h3 class="product-title">Studio Plant Pot</h3>
         <details id="component-state">
           <summary>Component state</summary>
           <dl>
-            <dt>cart</dt>
-            <dd id="state-cart">—</dd>
-            <dt>locale</dt>
-            <dd id="state-locale">—</dd>
-            <dt>orderConfirmation</dt>
-            <dd id="state-order-confirmation">—</dd>
+            <dt>checkout</dt>
+            <dd id="state-checkout">—</dd>
             <dt>error</dt>
             <dd id="state-error">—</dd>
-            <dt>sessionId</dt>
-            <dd id="state-session-id">—</dd>
+            <dt>target</dt>
+            <dd id="state-target">—</dd>
+            <dt>debug</dt>
+            <dd id="state-debug">—</dd>
           </dl>
         </details>
       </section>
@@ -130,8 +134,8 @@ <h2 id="events-heading">Events</h2>
         </div>
         <ul id="event-log"></ul>
         <p id="event-empty" class="muted">
-          Click <strong>Buy now</strong> to open checkout. Events the component dispatches will
-          appear here.
+          Open checkout and interact; <code>ec:*</code> and <code>checkout:close</code> events from
+          the component appear here.
         </p>
       </section>
     </main>

@@ -1,8 +1,6 @@
-// Importing the package registers the <shopify-checkout> custom element
-// as a side effect — once the component implementation lands. Today the
-// package only exports `VERSION`, so the element below renders as an
-// unknown HTML element and the playground produces no events at runtime.
-import "../src";
+// Registers `<shopify-checkout>` (same entry as published `@shopify/checkout-kit`).
+import "@shopify/checkout-kit";
+import type { ShopifyCheckout } from "@shopify/checkout-kit";
 
 import "./styles.css";
 
@@ -40,11 +38,10 @@ const buyNowButton = $<HTMLButtonElement>("#buy-now");
 const buyHint = $<HTMLParagraphElement>("#buy-hint");
 
 const stateNodes = {
-  cart: $<HTMLElement>("#state-cart"),
-  locale: $<HTMLElement>("#state-locale"),
-  orderConfirmation: $<HTMLElement>("#state-order-confirmation"),
+  checkout: $<HTMLElement>("#state-checkout"),
   error: $<HTMLElement>("#state-error"),
-  sessionId: $<HTMLElement>("#state-session-id"),
+  target: $<HTMLElement>("#state-target"),
+  debug: $<HTMLElement>("#state-debug"),
 };
 
 // ───── Mount the component (off-layout) ───────────────────────────────────
@@ -55,9 +52,11 @@ const stateNodes = {
 // called, so we attach it to <body> and leave the storefront panel free for
 // the merchant's product UI.
 
-const checkout = document.createElement("shopify-checkout");
+const checkout = document.createElement("shopify-checkout") as ShopifyCheckout;
 document.body.append(checkout);
 
+const checkoutEl: HTMLElement = checkout;
+
 // ───── Form ↔ attributes ──────────────────────────────────────────────────
 
 function setStringAttribute(el: HTMLElement, name: string, value: FormDataEntryValue | null): void {
@@ -72,6 +71,11 @@ function syncAttributes(): void {
   const data = new FormData(form);
   setStringAttribute(checkout, "src", data.get("src"));
   setStringAttribute(checkout, "target", data.get("target"));
+  if (data.has("debug")) {
+    checkout.setAttribute("debug", "");
+  } else {
+    checkout.removeAttribute("debug");
+  }
 
   refreshBuyButton(data.get("src"));
 }
@@ -123,24 +127,22 @@ for (const swatch of swatches) {
 
 // ───── Event log ──────────────────────────────────────────────────────────
 
+/** Dispatched by `ShopifyCheckout` (see `src/checkout.ts`). */
 const EVENT_TYPES = [
-  "checkout:start",
-  "checkout:complete",
+  "ec:start",
+  "ec:complete",
   "checkout:close",
-  "checkout:error",
-  "checkout:addressChangeStart",
-  "checkout:paymentMethodChangeStart",
-  "checkout:submitStart",
+  "ec:error",
+  "ec:lineItemsChange",
+  "ec:buyerChange",
+  "ec:totalsChange",
+  "ec:messagesChange",
 ] as const;
 
-const RESPONDABLE_EVENTS = new Set<string>([
-  "checkout:addressChangeStart",
-  "checkout:paymentMethodChangeStart",
-  "checkout:submitStart",
-]);
+const RESPONDABLE_EVENTS = new Set<string>([]);
 
 for (const type of EVENT_TYPES) {
-  checkout.addEventListener(type, () => {
+  checkoutEl.addEventListener(type, () => {
     appendLog(type);
     refreshState();
   });
@@ -152,20 +154,18 @@ clearLogButton.addEventListener("click", () => {
 
 function snapshotState(): Record<string, unknown> {
   return {
-    cart: checkout.cart,
-    locale: checkout.locale,
-    orderConfirmation: checkout.orderConfirmation,
+    checkout: checkout.checkout,
     error: checkout.error,
-    sessionId: checkout.sessionId,
+    target: checkout.target,
+    debug: checkout.debug,
   };
 }
 
 function refreshState(): void {
-  stateNodes.cart.textContent = formatValue(checkout.cart);
-  stateNodes.locale.textContent = formatValue(checkout.locale);
-  stateNodes.orderConfirmation.textContent = formatValue(checkout.orderConfirmation);
+  stateNodes.checkout.textContent = formatValue(checkout.checkout);
   stateNodes.error.textContent = formatValue(checkout.error);
-  stateNodes.sessionId.textContent = formatValue(checkout.sessionId);
+  stateNodes.target.textContent = formatValue(checkout.target);
+  stateNodes.debug.textContent = formatValue(checkout.debug);
 }
 
 function appendLog(type: string): void {

@@ -1,14 +1,13 @@
 {
   "extends": "../tsconfig.json",
   "compilerOptions": {
-    // The sample uses vanilla DOM patterns and a forward-looking shim
-    // (types.d.ts) for the not-yet-implemented component. Don't enforce the
-    // library-grade isolatedDeclarations rule here.
     "isolatedDeclarations": false,
     "declaration": false,
     "noEmit": true,
-    // vite/client provides the `*.css` module declaration so `import "./styles.css"` typechecks.
-    "types": ["vite/client"]
+    "types": ["vite/client"],
+    "paths": {
+      "@shopify/checkout-kit": ["../src/index.ts"]
+    }
   },
   "include": ["./**/*.ts", "./**/*.d.ts"]
 }
@@ -8,6 +8,12 @@ const here = dirname(fileURLToPath(import.meta.url));
 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"),
+    },
+  },
   build: {
     outDir: resolve(here, "dist"),
     emptyOutDir: true,

@@ -0,0 +1,34 @@
+/*
+MIT License
+
+Copyright 2023 - Present, Shopify Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+*/
+
+/* eslint ssr-friendly/no-dom-globals-in-module-scope: off */
+
+import { ShopifyCheckout } from "./checkout";
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "shopify-checkout": ShopifyCheckout;
+  }
+}
+
+customElements.define("shopify-checkout", ShopifyCheckout);