> ## Documentation Index
> Fetch the complete documentation index at: https://www.commercengine.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Svelte

> Integrate Commerce Engine Checkout into Svelte 5 apps with readable stores.

### NPM Package

<Card title="@commercengine/checkout" icon="npm" href="https://www.npmjs.com/package/@commercengine/checkout">
  Svelte integration for Commerce Engine Checkout.
</Card>

### Installation

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npm install @commercengine/checkout
```

### Setup

Call `initCheckout` once in your root layout or entry file. The SDK resolves the hosted URL from `storeId` + `environment` using store-specific subdomains:

```svelte +layout.svelte theme={"theme":{"light":"github-light","dark":"github-dark"}}
<script>
  import { initCheckout } from "@commercengine/checkout/svelte";

  initCheckout({
    storeId: "store_xxx",
    apiKey: "ak_xxx",
    environment: "production",
  });
</script>

<slot />
```

<Info>
  Feature flags, login methods, drawer direction, and payment provider are managed in Checkout Studio (Config API), not as SDK init options. Use `theme` only for per-session overrides.
</Info>

### Use the store

Import the `checkout` readable store and access it with `$checkout`:

```svelte CartButton.svelte theme={"theme":{"light":"github-light","dark":"github-dark"}}
<script>
  import { checkout } from "@commercengine/checkout/svelte";
</script>

<button on:click={$checkout.openCart} disabled={!$checkout.isReady}>
  Cart ({$checkout.cartCount})
</button>
```

### Fine-grained stores

For components that only need a single value, use the individual stores to minimize re-renders:

```svelte CartBadge.svelte theme={"theme":{"light":"github-light","dark":"github-dark"}}
<script>
  import { cartCount } from "@commercengine/checkout/svelte";
</script>

<span class="badge">{$cartCount}</span>
```

Available individual stores: `cartCount`, `cartTotal`, `isReady`, `isOpen`.

### Full example

```svelte App.svelte theme={"theme":{"light":"github-light","dark":"github-dark"}}
<script>
  import { initCheckout, checkout } from "@commercengine/checkout/svelte";

  initCheckout({
    storeId: "store_xxx",
    apiKey: "ak_xxx",
    environment: "production",
    onComplete: (order) => {
      window.location.href = `/thank-you?order=${order.orderNumber}`;
    },
  });
</script>

<nav>
  {#if $checkout.isLoggedIn}
    <span>Hi, {$checkout.user?.firstName}</span>
  {/if}
  <button on:click={$checkout.openCart} disabled={!$checkout.isReady}>
    Cart ({$checkout.cartCount})
  </button>
</nav>

<main>
  <button on:click={() => $checkout.addToCart("product_abc", "variant_xyz")}>
    Add to Cart
  </button>
</main>
```

### SvelteKit

For SvelteKit, initialize in the root layout. The SDK is client-only and safely no-ops during SSR.

```svelte src/routes/+layout.svelte theme={"theme":{"light":"github-light","dark":"github-dark"}}
<script>
  import { browser } from "$app/environment";
  import { initCheckout } from "@commercengine/checkout/svelte";

  if (browser) {
    initCheckout({
      storeId: "store_xxx",
      apiKey: "ak_xxx",
      environment: "production",
    });
  }
</script>

<slot />
```

<Tip>
  If your SvelteKit app also uses the `@commercengine/storefront` SDK, you **must** use `authMode: "provided"` with two-way token sync instead of the standalone example above. See [SvelteKit SDK Integration](/sdk/sveltekit-integration#hosted-checkout--sveltekit) for the full pattern.
</Tip>

### Store API reference

The `checkout` store value contains:

| Property                                     | Type               | Description                               |
| -------------------------------------------- | ------------------ | ----------------------------------------- |
| `isReady`                                    | `boolean`          | `true` when the checkout iframe is loaded |
| `isOpen`                                     | `boolean`          | `true` when the overlay is visible        |
| `cartCount`                                  | `number`           | Number of items in the cart               |
| `cartTotal`                                  | `number`           | Cart subtotal                             |
| `cartCurrency`                               | `string`           | Currency code                             |
| `isLoggedIn`                                 | `boolean`          | Whether a user is logged in               |
| `user`                                       | `UserInfo \| null` | Current user info                         |
| `openCart()`                                 | `function`         | Open the cart drawer                      |
| `openCheckout()`                             | `function`         | Open checkout directly                    |
| `close()`                                    | `function`         | Close the overlay                         |
| `addToCart(productId, variantId, quantity?)` | `function`         | Add an item to the cart                   |
| `updateTokens(accessToken, refreshToken?)`   | `function`         | Sync auth tokens                          |