Commmerce Docs
← Web Components

Web Components · Core & SDK

Commmerce SDK loader

The bootstrap script. Drop it once in <head>, and every <mmm-*> custom element on the page becomes interactive — React, ReactDOM, day.js, the Commmerce SDK, and the cart slider are loaded in parallel from a CDN, deduped, and wired to the store you specify.

Overview

Unlike every other entry in this reference, the SDK loader is not a custom element. It is a global JavaScript script — exposing window.CommmerceSDKLoader — that orchestrates everything else. Once it finishes, the rest of the <mmm-*> tags work.

What it does on first load:

  • DNS-prefetches and preconnects to the CDN origins it needs.
  • Loads react@18.3.1 and react-dom@18.3.1 from unpkg.
  • Loads dayjs@1.11.10 from jsDelivr.
  • Loads the Commmerce SDK init.js for the active store.
  • Fetches window.STORE_INFO_DATA and window.PREFERENCES if SSR hasn't already inlined them.
  • Auto-injects a <commmerce-cart-slider> element into <body> so checkout flows have a drawer to talk to.
  • Exposes a singleton — calling load() twice returns the same promise.

Install

Use the API host that matches your environment. The loader itself decides which downstream API host to call (localhost:4000 in dev, v2-api-staging for staging hosts, v2-api-production elsewhere) so you generally do not need to wire it up by hand.

<!-- Production -->
<script src="https://v2-api-production.commmerce.com/api/v1/web-component/commmerce-sdk.js?store=sample-store"></script>

<!-- Staging -->
<script src="https://v2-api-staging.commmerce.com/api/v1/web-component/commmerce-sdk.js?store=sample-store"></script>

<!-- Local dev (backend running on :4000) -->
<script src="http://localhost:4000/api/v1/web-component/commmerce-sdk.js?store=sample-store"></script>

One per page. The loader is a singleton — multiple <script> tags pointing at it deduplicate cleanly, but you should still keep it to one to avoid loading the bundle twice.

Query parameters

ParameterTypeDefaultDescription
storestringrequiredThe store code (tenant identifier). The loader replaces every [[STORE_CODE]] placeholder in downstream URLs with this value before fetching the SDK init script, the cart-slider bundle, store info, and preferences. Example: sample-store.

JavaScript API

After the script tag runs, window.CommmerceSDKLoader is the singleton you call into. It begins loading dependencies eagerly — calling load() just returns the in-flight (or completed) promise.

MethodReturnsDefault optionsDescription
load(options?)Promise<{loadTime,dependencies}>{}Kick off (or join) the dependency load. Resolves with the wall-clock load time and a map of which deps loaded.
load({skipOptional: true})PromisefalseSkip the cart-slider script (optional dependency). Use when the page never opens the cart.
load({onlyEssential: true})PromisefalseLoad only React + ReactDOM. Skip day.js, the SDK, store info, preferences, cart slider. Useful for lite landing pages.
isLoaded(dep)boolean—Check whether a named dependency finished loading. dep is one of react, reactDOM, dayjs, sdk.
isReady()boolean—True once every dependency in load()'s last call has resolved.
getState()object—Diagnostic snapshot — { initialized, loading, loaded, dependencies }. Read-only.

Globals it installs

The loader writes several globals onto window that downstream components and your own code can rely on:

GlobalTypeSourceDescription
window.CommmerceSDKLoaderobjectthis scriptThe singleton loader described above.
window.ReactmoduleunpkgReact 18.3.1 (UMD production build).
window.ReactDOMmoduleunpkgReactDOM 18.3.1 (UMD production build).
window.dayjsmodulejsDelivrDay.js 1.11.10.
window.CommmerceSDKclassSDK init.jsConstructor for per-component SDK instances — auth, cart, product, customer, checkout namespaces.
window.CommmerceUtilsobjectSDK init.jsHelper functions — formatters, URL helpers, debouncers.
window.CommmerceBaseStoreclassSDK init.jsBase class for component state stores.
window.CommmerceThemeSettingsobjectSDK init.jsReads window.STORE_THEME_SETTINGS; exposes branding, theme colours, typography, product settings, SEO, global code, breakpoints, plus 150+ generated CSS variables.
window.STORE_INFO_DATAobject|nullstoreinfo.phpStore metadata. Populated by SSR or fetched as fallback.
window.PREFERENCESobject|null/api/v1/preferencesEditor-saved preferences — nav menus, password protection, coming-soon flag.

Events

EventTargetPayload
commmerce:sdk-loadedwindow{ loadTime: number, dependencies: object }
commmerce:sdk-errorwindow{ error: Error }

Examples

1. Minimum viable storefront page

Place the loader once in <head> with your store code. Drop components anywhere.

<!DOCTYPE html>
<html>
<head>
  <script src="https://v2-api-production.commmerce.com/api/v1/web-component/commmerce-sdk.js?store=sample-store"></script>
</head>
<body>
  <mmm-header></mmm-header>
  <mmm-product-card data-product-id="classic-tee"></mmm-product-card>
  <mmm-footer></mmm-footer>
</body>
</html>

2. Wait for the SDK before running app code

Use the load promise to gate any code that depends on window.CommmerceSDK.

<script src="https://v2-api-production.commmerce.com/api/v1/web-component/commmerce-sdk.js?store=sample-store"></script>
<script>
  CommmerceSDKLoader.load().then(({ loadTime }) => {
    console.log('SDK ready in', loadTime.toFixed(0), 'ms');
    const sdk = new window.CommmerceSDK();
    sdk.cart.get().then(console.log);
  });
</script>

3. Skip the cart slider on a landing page

A campaign page that does not need the checkout drawer.

<script src="https://v2-api-production.commmerce.com/api/v1/web-component/commmerce-sdk.js?store=sample-store"></script>
<script>
  CommmerceSDKLoader.load({ skipOptional: true });
</script>

4. React-only mode

Use the loader to provide React + ReactDOM globally for a non-commerce widget.

<script src="https://v2-api-production.commmerce.com/api/v1/web-component/commmerce-sdk.js?store=sample-store"></script>
<script>
  CommmerceSDKLoader.load({ onlyEssential: true })
    .then(() => {
      const root = ReactDOM.createRoot(document.getElementById('app'));
      root.render(React.createElement('h1', null, 'Hello'));
    });
</script>

5. Listen for completion across the page

The loader dispatches a window event when everything resolves.

window.addEventListener('commmerce:sdk-loaded', (e) => {
  console.log('Total load:', e.detail.loadTime, 'ms');
  console.log('Loaded:', e.detail.dependencies);
});

Notes

  • The loader chooses the API host (localhost:4000 / v2-api-staging / v2-api-production) from window.location at runtime — you do not have to pick one yourself.
  • The cart slider script is fetched from the same API host. If it fails, the rest of the SDK still resolves successfully.
  • If window.STORE_THEME_SETTINGS is inlined by SSR before this script runs, CommmerceThemeSettings deep-merges over its defaults.
  • To debug, append &debug=1 to the loader URL (when supported by your build) or set window.__COMMMERCE_DEBUG__ = true before the script tag.