When upgrading the uStore server to a new version, you can continue using your custom themes in your live stores since the new uStore versions are backward compatible. However, if you’d like to benefit from the version's latest features, enhancements and bug fixes, it is advisable to upgrade your custom themes to uStore's latest version.

The upgrade should be performed after the uStore server has been upgraded to the latest version. First, download the out-of-the-box theme from the uStore server, as described in Getting Started > Setting up the environment, and extract it to a folder named themeName_latest. Then, choose one of the following options:

• Update the new version theme which you've just downloaded with the changes from your custom theme and create a new theme suitable for the new version.
• Use a file comparison tool (such as Beyond Compare) in order to compare the folder of the new theme files with the folder of your own custom theme. Now just copy all the new files, sections and changes from the new theme to your custom theme, without overriding your own changes. All folders should be copied except for: src/.next, node_modules, out and dist. Deleted files can also be deleted from your custom theme, unless used by your custom theme directly.
• In V17, NEXT.JS framework was removed, therefore, it's recommended to create a new Theme, based on the latest code and apply the changes from the custom Theme manually

Notes:

• If you detect changes in the package.json file, copy them as well and then run npm install on the theme project, as described in Getting Started > Setting up the environment.
• The config.json file of the upgraded theme includes the theme version. Changes in the config.json file must be copied to the custom theme as well.

In case you are upgrading your Custom Theme due to an internal revision changes, which weren't published by XMPie for bug fixes/ versions' upgrade of uStore, it's recommended to maintain your own revision build number in the Theme, see query parameter logic "rand" in "...\src\pages_document.js" file

uStore theme development requires a specific version of Node.js to be installed on your development computer:

• uStore v10 to v12 requires Node.js version 10.x. (Any other Node.js version is not supported.)
• uStore v12.1 and later requires Node.js 12.x. (Any other Node.js version is not supported.)
• If you have upgraded to version 13.4 with patch 1961 and higher or version 14.0 and later, it required node.js 16.3.0 (Any other Node.js version is not supported.)
• uStore v17.0 and later requires Node.js 18.18. (Any other Node.js version is not supported.)

If you are upgrading your theme from a version before uStore v12.1 to v12.1 or later, then after upgrading your custom theme as described above, you should install Node.js version 12. Without the Node.js upgrade, the theme will not start, and an error message will be displayed explaining the Node.js version mismatch.

Node.js installers can be downloaded from the Node.js website.

After installing Node.js, you may need to rebuild your node-sass package. You can do this by running 'npm rebuild node-sass'.

After all changes are updated in the theme, check the updated theme in your development environment. Open the updated theme folder in an IDE and continue as described in Getting Started > Setting up the environment.

For a detailed example, watch the Upgrading custom themes video on XMPie Campus.