> ## 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.

# Solid

> Integrate Commerce Engine Checkout into SolidJS apps with fine-grained reactive signals.

### NPM Package

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

### Installation

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

### Setup

Call `initCheckout` once at your app's entry point. The SDK resolves the hosted URL from `storeId` + `environment` using store-specific subdomains:

```tsx index.tsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { render } from "solid-js/web";
import { initCheckout } from "@commercengine/checkout/solid";
import App from "./App";

initCheckout({
  storeId: "store_xxx",
  apiKey: "ak_xxx",
  environment: "production",
});

render(() => <App />, document.getElementById("root")!);
```

### Use the primitive

`useCheckout()` returns an object with reactive getters (powered by Solid signals) and action methods:

```tsx CartButton.tsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { useCheckout } from "@commercengine/checkout/solid";

function CartButton() {
  const checkout = useCheckout();

  return (
    <button onClick={checkout.openCart} disabled={!checkout.isReady}>
      Cart ({checkout.cartCount})
    </button>
  );
}
```

<Info>
  Each property on the returned object is a getter backed by a Solid signal. Components only re-render when the specific values they access change.
</Info>

<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>

### Fine-grained signals

For minimal subscriptions, use the individual signal creators:

```tsx CartBadge.tsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { createCartCountSignal } from "@commercengine/checkout/solid";

function CartBadge() {
  const cartCount = createCartCountSignal();
  return <span class="badge">{cartCount()}</span>;
}
```

Available signal creators: `createCartCountSignal`, `createIsReadySignal`.

### Full example

```tsx App.tsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { Show } from "solid-js";
import { initCheckout, useCheckout } from "@commercengine/checkout/solid";

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

function Navbar() {
  const { openCart, cartCount, isReady, isLoggedIn, user } = useCheckout();

  return (
    <nav>
      <Show when={isLoggedIn}>
        <span>Hi, {user?.firstName}</span>
      </Show>
      <button onClick={openCart} disabled={!isReady}>
        Cart ({cartCount})
      </button>
    </nav>
  );
}

function ProductPage() {
  const { addToCart } = useCheckout();

  return (
    <button onClick={() => addToCart("product_abc", "variant_xyz")}>
      Add to Cart
    </button>
  );
}

export default function App() {
  return (
    <>
      <Navbar />
      <ProductPage />
    </>
  );
}
```

### SolidStart

For SolidStart, initialize in the root layout. The SDK no-ops during SSR.

```tsx root.tsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { initCheckout } from "@commercengine/checkout/solid";

if (typeof window !== "undefined") {
  initCheckout({
    storeId: "store_xxx",
    apiKey: "ak_xxx",
    environment: "production",
  });
}
```

### Primitive API reference

`useCheckout()` returns:

| Property                                     | Type                                 | Description                               |
| -------------------------------------------- | ------------------------------------ | ----------------------------------------- |
| `isReady`                                    | `boolean` (reactive getter)          | `true` when the checkout iframe is loaded |
| `isOpen`                                     | `boolean` (reactive getter)          | `true` when the overlay is visible        |
| `cartCount`                                  | `number` (reactive getter)           | Number of items in the cart               |
| `cartTotal`                                  | `number` (reactive getter)           | Cart subtotal                             |
| `cartCurrency`                               | `string` (reactive getter)           | Currency code                             |
| `isLoggedIn`                                 | `boolean` (reactive getter)          | Whether a user is logged in               |
| `user`                                       | `UserInfo \| null` (reactive getter) | 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                          |