From eb5500393448b679db5e240bc50538d7bf11dc57 Mon Sep 17 00:00:00 2001 From: Westin Wrzesinski Date: Thu, 14 May 2026 23:26:32 -0500 Subject: [PATCH] Expand Web Platform README --- platforms/web/README.md | 297 +++++++++++++++++++++++++++++++++++----- 1 file changed, 259 insertions(+), 38 deletions(-) diff --git a/platforms/web/README.md b/platforms/web/README.md index a2d42523..02db5a85 100644 --- a/platforms/web/README.md +++ b/platforms/web/README.md @@ -1,57 +1,278 @@ -# @shopify/checkout-kit +# Shopify Checkout Kit - Web -A web component for embedding Shopify checkout in any website. +[![GitHub license](https://img.shields.io/badge/license-MIT-lightgrey.svg?style=flat)](https://github.com/Shopify/checkout-kit/blob/main/LICENSE) [![npm latest](https://img.shields.io/npm/v/@shopify/checkout-kit/latest.svg?label=npm)](https://www.npmjs.com/package/@shopify/checkout-kit) -[![npm latest](https://img.shields.io/npm/v/@shopify/checkout-kit/latest.svg?label=npm)](https://www.npmjs.com/package/@shopify/checkout-kit) +gradients -## Install +**Shopify Checkout Kit** is a web component library that enables any website to +present the world's highest converting, customizable, one-page checkout. The +presented experience is a fully-featured checkout that preserves all of the +store customizations: Checkout UI extensions, Functions, branding, and more. It +also provides web idiomatic defaults such as opening checkout in a popup or +new tab, a transient overlay scrim while the popup is open, and convenient +developer APIs to embed, customize, and follow the lifecycle of the checkout +experience via the +[Embedded Checkout Protocol](https://ucp.dev/2026-04-08/specification/embedded-checkout/). -```bash -npm i @shopify/checkout-kit +Check out our blog to +[learn how and why we built the Shopify Checkout Kit](https://www.shopify.com/partners/blog/mobile-checkout-sdks-for-ios-and-android). + +- [Platform Requirements](#platform-requirements) +- [Getting Started](#getting-started) + - [Installation](#installation) +- [Basic Usage](#basic-usage) +- [Programmatic Usage](#programmatic-usage) +- [Usage with the Shopify Storefront API](#usage-with-the-shopify-storefront-api) +- [Configuration](#configuration) + - [`src`](#src) + - [`target`](#target) + - [`debug`](#debug) + - [Popup dimensions](#popup-dimensions) + - [Overlay scrim](#overlay-scrim) +- [Explore the sample app](#explore-the-sample-app) +- [Contributing](#contributing) +- [License](#license) + +## Platform Requirements + +- **Browsers** — evergreen Chromium, Firefox, and WebKit (Safari 16.4+). The + component relies on ``, native `customElements`, and `AbortController` + — all stable in every supported browser. +- **TypeScript** (optional) — `5.0+` for consumers using the bundled type + definitions. +- **Bundler** (optional) — works with Vite, Rollup, esbuild, webpack, or + no bundler at all via ` ``` -## Development +The element has no visible layout of its own beyond a transient `` +scrim that appears over the host page while the popup is open. It can sit +anywhere in your DOM. -```bash -cd platforms/web -pnpm install +See [usage with the Storefront API](#usage-with-the-shopify-storefront-api) +below for details on how to obtain a checkout URL. -pnpm build # vite + custom-elements-manifest -pnpm dev # vite build --watch -pnpm test # vitest with coverage -pnpm test:watch -pnpm lint # typecheck + oxlint + oxfmt --check -pnpm format # oxfmt (writes in place) -pnpm verify # publint +## Programmatic Usage -pnpm sample # serve the playground at http://localhost:5173 -pnpm sample:build # build the playground (sample/dist/) +If you'd rather not declare the element in HTML, create one from JavaScript: + +```ts +import '@shopify/checkout-kit'; +import type {ShopifyCheckout} from '@shopify/checkout-kit'; + +const checkout = document.createElement('shopify-checkout') as ShopifyCheckout; +checkout.src = 'https://your-store.myshopify.com/checkouts/cn/abc123'; +checkout.target = 'popup'; +document.body.append(checkout); + +checkout.addEventListener('ec:complete', () => { + console.log('Order complete', checkout.checkout); +}); + +checkout.open(); +// Later: +checkout.close(); +``` + +The `ShopifyCheckout` class is also exported directly if you want to import +the constructor without registering the element globally: + +```ts +import {ShopifyCheckout} from '@shopify/checkout-kit'; + +if (!customElements.get('shopify-checkout')) { + customElements.define('shopify-checkout', ShopifyCheckout); +} ``` -## Tooling +## Usage with the Shopify Storefront API + +To present checkout you first need a checkout URL. The most common way is to +use the [Storefront GraphQL API](https://shopify.dev/docs/api/storefront) to +assemble a cart (via `cartCreate` and related mutations) and read the +[`checkoutUrl`](https://shopify.dev/docs/api/storefront/2024-10/objects/Cart#field-cart-checkouturl) +field. Alternatively, a +[cart permalink](https://help.shopify.com/en/manual/products/details/cart-permalink) +can be provided. + +```ts +const response = await fetch( + 'https://your-store.myshopify.com/api/2024-10/graphql.json', + { + method: 'POST', + headers: { + 'Content-Type': 'application/json', + 'X-Shopify-Storefront-Access-Token': '', + }, + body: JSON.stringify({ + query: /* GraphQL */ ` + query CheckoutUrl($id: ID!) { + cart(id: $id) { + checkoutUrl + } + } + `, + variables: {id: 'gid://shopify/Cart/...'}, + }), + }, +); + +const {data} = await response.json(); +checkout.src = data.cart.checkoutUrl; +``` + +> [!IMPORTANT] +> `src` must be an `https:` URL. The component drops invalid or non-HTTPS +> values and refuses to open. When `debug` is enabled, a warning is logged +> to the console. + +## Configuration + +The presented checkout is customized via attributes on the +`` element (or the equivalent properties on the +`ShopifyCheckout` instance — both are reflected). + +### `src` + +The URL of the checkout to load. Typically `cart.checkoutUrl` from the +Storefront API. + +```html + +``` + +```ts +checkout.src = 'https://your-store.myshopify.com/checkouts/cn/abc123'; +``` + +The component appends a handful of query parameters to `src` when it opens +checkout: `ec_version` (Embedded Checkout Protocol version), +`ec_delegate` (which capabilities the host delegates), and `ck_version` +(the Checkout Kit version). + +### `target` + +Where the checkout is presented. Defaults to `"auto"`. + +| Value | Behavior | +| ---------- | ------------------------------------------------------------------- | +| `"auto"` | Opens checkout in a new browser tab (default). | +| `"popup"` | Opens checkout in a popup window sized and centered over the page. | +| `"_blank"` | Synonym for `"auto"` — new tab. | +| _(string)_ | Any other value is treated as a named window target, the same as the [`target` parameter of `window.open()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/open#target). | + +```html + +``` + +> [!NOTE] +> `"_self"`, `"_parent"`, and `"_top"` are not allowed — they would navigate +> the host page away. The component falls back to `"auto"` if you set one, +> and logs a warning when `debug` is enabled. + +### `debug` + +Enables console diagnostics during integration. Useful while wiring up `src` +and event handlers; turn it off in production. + +```html + +``` + +### Popup dimensions + +When `target="popup"`, the popup is centered over the host window. Defaults +are `600 × 600`, capped at 90% of the host window. Override via CSS custom +properties: + +```css +shopify-checkout { + --shopify-checkout-dialog-width: 720; + --shopify-checkout-dialog-height: 800; +} +``` + +### Overlay scrim + +While a popup is open the component renders a `` scrim over the host +page, with a "Continue your purchase in the checkout window" link and a close +button. Hide it by either: + +- Setting `display: none` on the element itself, or +- Targeting the `overlay` shadow part: + +```css +shopify-checkout::part(overlay) { + display: none; +} +``` + +## Explore the sample app + +See the [`sample/`](./sample) directory for a small Vite playground that mounts +the real `` element next to a faux storefront. Run it from +this directory with: + +```sh +pnpm install +pnpm sample +``` + +Then open the dev server URL and paste a valid checkout URL into the `src` +field to try `open()` / `close()` / `focus()` and see the live event stream. + +## Contributing -| Concern | Tool | -| --------------- | -------------------------------------------- | -| Bundler | Vite (lib mode) + `vite-plugin-dts` | -| Tests | Vitest + happy-dom | -| Lint | oxlint | -| Format | oxfmt | -| Element docs | `@custom-elements-manifest/analyzer` → `dist/custom-elements.json` | -| Publish hygiene | `publint` | +We welcome code contributions, feature requests, and reporting of issues. +Please see [guidelines and instructions](../../.github/CONTRIBUTING.md). ## License -[MIT](./LICENSE) +Shopify's Checkout Kit is provided under an [MIT License](LICENSE).