Mini Cart (built on Cornerstone)

This repo is a mini cart built on top of BigCommerce Stencil’s Cornerstone theme.

Features

1. Fast UI (optimistic updates for remove/clear/add flows)
2. Item quantity debouncing (per-line-item debounced API updates)
3. Stale request protection (guards against out-of-order async renders)
4. Parallel fetching (mini cart HTML + cart JSON fetched concurrently)
5. Skeleton/loading states (immediate feedback while cart updates)
6. Accessible interactions (aria-busy loading state + Esc to close)

Important code snippets

Fast: optimistic remove + instant UI feedback

When removing an item, we optimistically update the DOM immediately for a snappy UX, then reconcile with the API (and restore if it fails).

// assets/js/theme/cart/miniCart.js
// Optimistic remove for instant UX; restore on failure.
itemNode?.remove();
beginFooterLoading();

try {
  await cartService.removeItem(itemId);
  const cart = await cartService.getCart(cartId);
  const quantity = computeCartItemCount(cart);

  if (!quantity) {
    await syncCart();
  } else {
    await syncFooterAndQuantity();
  }
} catch (error) {
  showAlertModal(error?.message || "Unable to remove cart item.");

  if (itemsParent && nextSibling) {
    itemsParent.insertBefore(itemNode, nextSibling);
  } else if (itemsParent && itemNode) {
    itemsParent.appendChild(itemNode);
  }
}

Fast: parallel fetch for render + state

Cart HTML and cart JSON are fetched in parallel, then rendered in one pass (guarded by a request id to avoid stale updates).

// assets/js/theme/cart/miniCart.js
const [html, cart] = await Promise.all([
  cartService.getMiniCartContent(),
  cartService.getCart(cartId),
]);

cartRenderer.render(html);
bindDynamicEvents();

Debouncing: coalesce quantity updates per line item

Quantity updates are debounced per item id so rapid clicks/typing don’t spam the API.

// assets/js/theme/cart/miniCart.js
if (!qtyDebouncers.has(itemId)) {
  qtyDebouncers.set(itemId, debounce(runQtyUpdate, 400));
}

qtyDebouncers.get(itemId)(itemId, qty, baselineQty);

File structure (mini cart)

assets/js/theme/cart/
  miniCart.js        # controller: events, debouncing, API calls, open/close
  cartRenderer.js    # DOM rendering + optimistic/skeleton UI helpers
  cartService.js     # BigCommerce cart API calls + mini cart HTML fetch
  cartState.js       # in-memory state + request id tracking

assets/scss/components/stencil/miniCart/
  _miniCart.scss     # mini cart styles

templates/layout/
  base.html          # mini cart markup mount + trigger hooks (theme layout)

Triggering add-to-cart from any page

Mini cart listens globally for clicks on add-to-cart buttons that match:

• [data-button-type="add-cart"]

If the element has (or can derive) a product id, the mini cart will:

• Open immediately
• Show a skeleton row (or item-level loading if the item already exists)
• Call the cart API to add the item
• Re-sync the mini cart contents