Install the widget

Write the config object first, then load the script. The widget reads window.subblyConfig the moment it runs, so the order matters.

Embed the widget
<!-- 1. Configure -->
<script>
  window.subblyConfig = {
    apiKey: 'YOUR_STOREFRONT_API_KEY'
  }
</script>

<!-- 2. Load -->
<script type="module" src="https://assets.subbly.co/cart/cart-widget.js"></script>

Your Storefront API key is in the Subbly admin, under Settings, Developers.

The script tag carries no data- attributes; everything goes through the config object. cart-widget.js is a small loader that imports the real bundle and its stylesheet, so do not cache it. The files it pulls from assets/ carry a hash in the name and can be cached for a long time.

Wait for the widget

The script loads asynchronously. The widget fires two events on window. Neither carries data.

There is no ready callback and no command queue. Guard against the event having already fired:

Run code once the widget is ready
const onReady = (fn) => {
  if (window.subblyCart) {
    fn(window.subblyCart)
    return
  }

  window.addEventListener('subbly-cart-initialized', () =>
    fn(window.subblyCart)
  )
}

onReady((cart) => {
  cart.open()
})

The other pages in this section use this onReady helper.

The widget also emits its own CART_READY event, but it fires inside initialize(), before the instance is handed out, so no handler of yours can see it. Read the cart from subblyCart.cart once subbly-cart-initialized has fired instead.

Next steps

• Configure — the keys of window.subblyConfig.
• Wire it into your page — buy links, your own cart button and the container.