Using uStore as a web component - XMPieLab/uStore-NG GitHub Wiki

As of version 25.2, uStore can be used as a web component in external applications when using uStore Connect or uStore Connect Enterprise.

To integrate uStore as a web component in external applications (uStore Connect or uStore Connect Enterprise), include these resources in your HTML.

uStore 26.3 and above

<html>
  <head>
    <script>window.uStoreConfig = {
      assetPrefix: '/ustorethemes/<theme name>',
      uStoreRemoteServerUrl: '<url to ustore>',
    }
    window.uStoreDucs = []</script>

    <script defer src="<url to ustore>/ustorethemes/<theme name>/static/js/x-store.js"></script>
  </head>
  <body>
    <x-ustore url="<url you got from the uStore Connect Rest API>"></x-ustore>
  </body>
</html>

React is bundled inside x-store.js and is no longer loaded from a CDN. Do not add react, react-dom or prop-types script tags — see React and the host page.

uStore 25.2 to 26.2

<html>
  <head>
    <script>window.uStoreConfig = {
      assetPrefix: '/ustorethemes/<theme name>',
      uStoreRemoteServerUrl: '<url to ustore>',
    }
    window.uStoreDucs = []</script>

    <script crossorigin="" src="https://cdnjs.cloudflare.com/ajax/libs/react/18.2.0/umd/react.production.min.js"></script>
    <script crossorigin="" src="https://cdnjs.cloudflare.com/ajax/libs/react-dom/18.2.0/umd/react-dom.production.min.js"></script>
    <script crossorigin="" src="https://cdnjs.cloudflare.com/ajax/libs/prop-types/15.7.2/prop-types.min.js"></script>

    <script defer src="<url to ustore>/ustorethemes/<theme name>/static/js/x-store.js"></script>
  </head>
  <body>
    <x-ustore url="<url you got from the uStore Connect Rest API>"></x-ustore>
  </body>
</html>

Replace <theme name> with the name of the theme you are using, and <url to ustore> with the URL of your uStore instance.

See the uStore Connect documentation at https://<ustore url>/uStoreRestAPI/#/SingleSignon/SingleSignon. The result of the call is a URL that you can use in the x-ustore component. When you supply the url attribute to the x-ustore component, it loads the uStore instance and displays the store in your application.

From uStore 26.3 the storefront runs on React 19, which does not publish a UMD build — the CDN script tags used up to 26.2 have no React 19 equivalent. x-store.js therefore contains React itself and publishes window.React, window.ReactDOM and window.PropTypes before the component mounts, so input controls (DUCs) and widgets continue to resolve those globals exactly as before. No change is required to an existing DUC or widget.

Two consequences for the host page:

• Remove the CDN script tags when upgrading to 26.3. Left in place they download roughly 130 KB that is immediately discarded, because x-store.js overwrites the globals they set.
• The host page cannot use React globally itself. x-store.js assigns window.React unconditionally. A host page that keeps its own React on window will have it replaced, and mixing the two produces a second React instance in which every hook inside a DUC fails.

If your host application uses React internally through a bundler (imports rather than a global), it is unaffected.

The uStore AquaBlue theme has been modified to support being used as a web component. If you are developing a custom theme, you can use the AquaBlue theme as a reference. Make sure the following requirements are met:

1. The theme must be able to run in a web component context: it must not assume the host page supplies React or any other global library, and it must not rely on styles that are not scoped to the component.
2. The theme must be able to load the uStore Connect or uStore Connect Enterprise scripts and styles.
3. If you are using npm packages, make sure they are compatible with web components and do not rely on global variables or styles that are not scoped to the component.

To run the development server, use the following command:

npm start -- server=<url to ustore> wc=1

Once the development server is running, you can access the uStore instance in your browser at http://localhost:3000. You will get to a configuration page where you can enter the URL of your uStore instance, and a JSON with a list of payloads that will be used for the Rest API calls. Click "Save", and then use the "Connect to" menu to select the product or store you wish to connect to.

Building the theme has not changed. Use the following command to build the theme:

npm run publish -- name=<name> displayName=<display name>