The Shopify plugin connects the Stylux JavaScript SDK to Shopify's AJAX cart API. It registers a cart adapter, keeps personalized cart lines balanced, detects variant changes, and can open Stylux from the theme's add to cart button.

Use this plugin for standard Shopify online store themes. Headless Shopify storefronts should still install the Stylux Shopify application for product, order, and fulfillment sync, but should provide a custom cart adapter instead of using the theme plugin.

Getting Started

Load the SDK asynchronously, then enable the plugin in that setup call:

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

With shopify: true, the plugin uses its defaults and enables cart normalization. Pass an object to customize its behavior.

Configuration

Name	Type	Description
`detectVariantChanges`	`boolean`	Detects product variant changes; defaults to `true`
`overrideAddToCart`	`boolean`	Opens Stylux from matching add to cart controls; defaults to `true`
`addToCartSelector`	`string`	Add to cart control selector; defaults to `[name="add"], [name="add"] *`
`activeVariantIdSelector`	`string`	Active variant input selector; defaults to `input[name="id"], select[name="id"]`
`normalizeCart`	`boolean`	Legacy fallback for `cart.normalize`; defaults to `true` when the plugin is enabled
`sectionsForCartRequests`	`string \| string[]`	Shopify sections included in AJAX cart requests
`getQuantity`	`() => number`	Optional. Returns the active PDP quantity for offer flows that do not specify one. Defaults to `input[name="quantity"]`, or `1` if that input is missing. If the PDP has a quantity selector, this should return the currently selected quantity.
`getLineItemProperties`	`(config) => properties \| Promise<properties>`	Adds or changes line item properties for checkout adds
`getActiveSellingPlanId`	`(config) => id \| null \| Promise<id \| null>`	Returns the selling plan for a product
`beforeUpdateCart`	`(config) => void \| Promise<unknown>`	Adds extra lines before an `ADD_TO_CART` write
`afterUpdateCart`	`(payload) => void \| Promise<unknown>`	Runs after a completed cart transaction. V1 receives the Shopify cart; V2 receives `{ action, cart }`
`afterUpdateCartVersion`	`'V1' \| 'V2'`	Chooses the `afterUpdateCart` payload; defaults to `V1`
`nestedCartLines`	`boolean`	Uses Shopify nested cart line relationships; defaults to `false`

Prefer cart.normalize over plugins.shopify.normalizeCart:

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

Cart Transaction Hooks

beforeUpdateCart runs before checkout adds and can append Shopify line items:

beforeUpdateCart({ action, addLineItems }) {
  if (action === 'ADD_TO_CART') {
    addLineItems({
      items: {
        id: 'variant-id',
        quantity: 1,
      },
    });
  }
}

afterUpdateCart runs from the Shopify adapter's transaction completion behavior. The default V1 callback receives the Shopify cart. V2 receives the cart and the action that caused the transaction:

plugins: {
  shopify: {
    afterUpdateCartVersion: 'V2',
    afterUpdateCart({ action, cart }) {
      // refresh storefront cart UI for this action
    },
  },
}

Actions are ADD_TO_CART, CART_NORMALIZATION, UPDATE_CART, CLEAR_CART, and UPDATE_ATTRIBUTES. Check action and run the side effects that action needs. See Cart Adapter.

If no afterUpdateCart hook is set, ADD_TO_CART redirects to /cart. CART_NORMALIZATION, UPDATE_CART, and CLEAR_CART reload when the customer is already on a cart URL. UPDATE_ATTRIBUTES does not reload the cart.

Using a Custom Adapter

If cart.adapter is provided, the plugin does not replace it. Shopify cart behavior such as beforeUpdateCart, extra line item properties, selling plans, the default redirect, and afterUpdateCart belongs to the built-in Shopify adapter and will not run automatically.

Variant detection and add to cart override still work. Implement the cart behavior you need in your custom adapter's transact method.