Solid - Commerce Engine Docs

NPM Package

@commercengine/checkout

SolidJS integration for Commerce Engine Checkout.

Installation

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:

index.tsx

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:

CartButton.tsx

import { useCheckout } from "@commercengine/checkout/solid";

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

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

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.

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.

Fine-grained signals

For minimal subscriptions, use the individual signal creators:

CartBadge.tsx

import { createCartCountSignal } from "@commercengine/checkout/solid";

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

Available signal creators: createCartCountSignal, createIsReadySignal.

Full example

App.tsx

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.

root.tsx

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

​NPM Package

@commercengine/checkout

​Installation

​Setup

​Use the primitive

​Fine-grained signals

​Full example

​SolidStart

​Primitive API reference

NPM Package

Installation

Setup

Use the primitive

Fine-grained signals

Full example

SolidStart

Primitive API reference