Setup

Load the SDK asynchronously on every storefront page where Stylux is used. Define window.Stylux with queue and onScriptLoad, inject the script with async, and call Stylux.setup once it loads:

window.Stylux = {
  queue: [],
  onScriptLoad: (fn) => {
    window.Stylux.queue.push(fn);
  },
};

(function loadStyluxSDK(src, onload) {
  const script = document.createElement('script');
  script.src = src;
  script.async = true;
  script.crossOrigin = 'anonymous';
  script.onload = onload;
  document.head.appendChild(script);
})('https://sdk.stylux.io/js-sdk.js', async () => {
  if (!self.Stylux) {
    return;
  }

  await Stylux.setup({
    apiKey: 'STLX_key-for-unsigned-requests',
    merchantId: 'merchant-id',
  });
});

An async script never blocks parsing or rendering, so the SDK stays off the critical path and does not hold up page load speed, site speed, or time to first paint. queue covers the gap while the script is in flight: anything the storefront passes to Stylux.onScriptLoad before then is replayed once the real SDK takes over the global.

Use the frontend API key issued for unsigned browser requests. Never expose a signed API secret in storefront code.

Only apiKey and merchantId are required. The rest of this page documents optional Stylux.setup fields. Later examples show only the options that change; they still belong inside that load callback.

Name	Type	Description
`apiKey`	`string`	Frontend API key for unsigned browser requests
`merchantId`	`string`	Stylux merchant ID
`cart`	`CartConfig`	Cart adapter and normalization behavior
`plugins`	`PluginConfig`	Optional platform plugins, including Shopify
`modal`	`ModalConfig`	Modal version and button styles
`preload`	`boolean \| PreloadConfig`	Assets to load during setup; defaults to enabled
`selectors`	`SelectorConfig`	Containers for offer and modal types
`getButtonOfferText`	`(config: { ctaText?: string \| null; price?: string \| null; priceAsNumber: number }) => string`	Renders button text. Defaults to `Personalize it`, with `$priceAsNumber` appended when the price is nonzero
`offerElementId`	`string \| SelectorInfo`	Legacy button offer container; defaults to `#stylux-offer-container`
`modalElementId`	`string \| SelectorInfo`	Legacy modal container; defaults to `#stylux-modal-container`

Cart Configuration

Use cart to connect the SDK to the storefront cart:

await Stylux.setup({
  apiKey: 'STLX_key-for-unsigned-requests',
  merchantId: 'merchant-id',
  cart: {
    adapter: cartAdapter,
    mutationPathFragments: ['/api/cart'],
    normalize: true,
  },
});

Name	Type	Description
`adapter`	`ICartAdapter`	Storefront cart implementation. See Cart Adapter
`normalize`	`boolean`	Keeps lines in a Stylux bundle balanced. Defaults to `false`, or `true` when the Shopify plugin is enabled
`mutationPathFragments`	`CartMutationMatcher[]`	Matchers that trigger normalization after a storefront cart request. Strings still match URL path fragments; entries may also be path regular expressions, request functions, or `{ path, method, body }` objects. See Cart Adapter

The Shopify plugin registers its own adapter and common Shopify mutation paths. An adapter you provide takes priority.

Shopify Plugin

For standard Shopify themes:

await Stylux.setup({
  apiKey: 'STLX_key-for-unsigned-requests',
  merchantId: 'merchant-id',
  plugins: {
    shopify: true,
  },
});

See SDK Shopify Plugin for its complete configuration.

Modal Configuration

The modal renders in a separate frame so its styles remain consistent across storefronts. MODAL_V2 is the default. The short form V2 is also accepted; use B2B for the B2B modal.

await Stylux.setup({
  apiKey: 'STLX_key-for-unsigned-requests',
  merchantId: 'merchant-id',
  modal: {
    buttonStyles: {
      background: '#0000FF',
      color: '#FFF',
      'border-radius': '2px',
    },
  },
});

To configure the modal version explicitly:

await Stylux.setup({
  apiKey: 'STLX_key-for-unsigned-requests',
  merchantId: 'merchant-id',
  modal: {
    version: 'V2',
  },
});

Preloading

Preloading is enabled by default. Set it to false for a custom integration that does not use built in visual components, or choose specific assets:

await Stylux.setup({
  apiKey: 'STLX_key-for-unsigned-requests',
  merchantId: 'merchant-id',
  preload: {
    modals: ['MODAL_V2'],
    offers: ['BUTTON'],
  },
});

Selectors

Use selectors when an offer or modal should render somewhere other than its default container. It supports regular CSS selectors and selectors inside a parent shadow root. The legacy offerElementId and modalElementId options remain supported.