Getting started - XMPieLab/uStore-NG GitHub Wiki

This section will teach you how to set up the theme development environment and some theme technology basics, so you can start developing a theme using the new technology. Note that this technology can be used in stores built in version 10.0 and above.

Environment prerequisites

• A local machine with the Node.js installed.

  • For uStore v10 through v12.0, Node.js version 10.x is mandatory.
  • For uStore v12.1 through v13.4, Node.js version 12.x is mandatory.
  • For uStore v13.4 with patch 1961 and higher or v14 or later, Node.js version 16.3 is mandatory.
  • For uStore v17.0, Node.js version 18.18 is mandatory.
  • For uStore v17.2 through 25.3, Node.js version 20.18 and Python version 3.9 are mandatory.
  • For uStore v.26.1 and higher, the theme development environment requires NodeJS version 24.14.1.

• The React version the theme runs on is set by uStore, not by you.

  uStore version	React
  26.3 and above	19.2.8, pinned exactly in the theme's package.json
  26.2 and below	React 18.x — read the exact version from that release's theme package.json

  Two consequences. Input controls (DUCs) and widgets never bundle their own React: they bind to the globals the storefront publishes, so they follow the host version automatically. And a third-party React package whose peer range stops at React 18 will refuse to install next to React 19 — add an overrides entry rather than installing with --legacy-peer-deps, which permits a second React runtime in which every hook throws. See Adding an external package.

• An Integrated Development Environment (IDE) for theme editing, such as Visual Studio Code, or Notepad++ with Command Prompt.

uStore prerequisites

• A uStore server version 10 and above which you can access over HTTP from your local machine.
• An online NG store (i.e. test store) available on uStore Back Office. The store should have at least one product category with at least one online product.
• A uStore user who has permissions to access the test store.
• (Optional) Credentials of a uStore user who has permissions to access uStore Back Office. This will enable you to download the initial theme package and upload the developed theme back to the server.

1. Open uStore Back Office and go to Presets > Theme Management.

2. Download XMPie’s AquaBlue theme to your local machine and extract the folder.

3. Open the theme folder in an IDE, open the terminal and change the folder to src as follows:

   cd src

   The terminal path will now direct to the src folder.

4. Install the node packages. In the terminal type:

   npm install

   All node packages will be installed without errors. You can ignore any warnings.

   NOTE: If you have uStore version 13.4 with patch 1961 and higher or version 14.x, please use the command: npm install --legacy-peer-deps This is not required for uStore version 17.0 and later.

5. Start the application on the local node server, giving the uStore server URL as the parameter where the test store is located, and the API calls are directed to. In the terminal type:

   npm start -- server=<uStoreServerUrl>

   The theme will compile and you can browse to the local development server. If there are compilation errors, they will be listed in the terminal.

   NOTE: <uStoreServerUrl> is the full URL to the server, including the protocol and the external domain or server IP, e.g. https://uStoreServer-address.com/ or http://216.58.216.164/

   • uStore 26.3 or later — both http and https server URLs are fully supported, so the store can be defined as Secured (using https / SSL connection). API calls are routed through the local dev proxy, so no extra setup is needed. To also run the local dev server itself over HTTPS (required for hybrid pages — where .NET components are loaded into an iframe — when working against an https server), install mkcert and run npm run cert once; the dev server will then automatically start on https://localhost:3000/.
   • uStore 17.2 – 26.2 — you can use https, but hybrid pages will not be available.
   • uStore before 17.2 — the protocol must be http, and the store should be defined as "Not Secured" (it is recommended to have a staging server or a testing store).

6. Open a browser and in the address line type the following URL:

   http://localhost:3000/ustore?storeid=<storeID>&devmode=true&devthemename=<themeName>

   where the parameters are:

   storeID – The ID of your test store. The store ID can be found in the store list in uStore Back Office.

   devmode – Denotes that the environment is set to development.

   devthemename – The name of the theme that was originally downloaded (the value is case-sensitive so look for the value in the config.json file under "name" key).

   NOTES:

   • The port number has changed from 5000 to 3000 due to intersection with Mac used ports.
   • These parameters should always be present in the URL before logging into the store, in order to have a working development environment. Add them again if you are redirected to the login page during theme development as they will be removed from the URL.

7. Log in to the store and check that the homepage is up and running.

8. Develop the theme on the local environment as you would any other React project.

9. When development is completed, create a theme package and upload it to the uStore Back Office, as described in Publishing the Theme.

The theme application is constructed of several areas, each built using a different technology.

• The new areas of the application are the homepage, category page, header and footer, which are written in ReactJS technology. They have a modern UI and a responsive layout.

• The remaining areas are legacy pages, written in ASPX and .NET technology. Their style is controlled by the legacy skin, adapted to work with the theme technology. The skin has a mobile version and is also supported in mobile devices in most areas of the application.

The legacy pages are hosted inside an iframe in the new React pages, so in fact routing is carried out using the React routing mechanism to enable a natural flow of navigation in the store. The new React code includes a page with an iframe for each of the legacy pages, referred to as “hybrid” pages.

The React areas in the application and their style are entirely controlled by the theme development process. This is not the case for legacy pages. The code of legacy pages cannot be modified and the page style can be controlled only via the existing variables of the theme.

Notice that while developing the new areas of the theme, changes that you make to variables cannot be seen in legacy pages in the development environment. They will be visible only when you publish the theme and assign it to a store.

See here for mkcert installation methods

Notes:

1. After installing mkcert, you need to open a new terminal window before running npm run cert, so that the updated PATH is picked up.
2. The first run of npm run cert will ask for elevated permissions (UAC prompt on Windows, password on macOS). This is expected, because mkcert is adding its local certificate authority to the system trust store. This happens only once; after that, npm start will automatically serve on https://localhost:3000

For a detailed example, watch the Setting up the development environment video in XMPie Campus.