Upgrading to 4.0 and later

Storefront Toolkit version 4.0 and later use version 16.x or 18.x of Node.js as a prerequisite. This represents a significant change that came about after versions 10.x and 12.x of Node.js were deprecated.

If you have installed version 3.x.x of Storefront Toolkit and later upgrade to version 4.0, you can continue to use and work on existing themes originally created in the earlier Toolkit versions. However, you may encounter warnings and other issues as a result of the change.

This section describes the issues you may encounter as the result of an upgrade, and provides advice on how to address them.

Deprecation warnings

Some commands (checkout, start, and package) may display deprecation warnings. These do not prevent the commands from functioning unless there is also an error.

These deprecation warnings are the result of minor incompatibilities which arise because the SASS files for the Toolkit are now compiled with Dart Sass rather than node-sass.

You can fix this issue by using the math.div or calc functions when employing division in a SASS file. If you update related items in your theme, the warnings should no longer appear.

Existing themes with custom components

If an existing theme includes custom components, you may encounter an error when using the start command: Can't resolve scheduler/tracing.

This error occurs due to a difference in the version of React used by each version of the Toolkit. Version 4.0 of the Toolkit uses a version of React (16.14.0) that has renamed schedule/tracking to schedule/tracing, and is thus unable to find schedule/tracking when it is cited in an older theme.

To fix this issue in your theme, run the storybook command. The start command should then work normally afterward.

note

About @appdirect/sfb-theme-components

It is not possible to upgrade @appdirect/sfb-theme-components to the latest version while using an earlier version of the Toolkit. You must upgrade your Toolkit to version 4.0 to get the latest (0.0.293) @appdirect/sfb-theme-components update.

Existing themes based on Classic theme

If an existing theme is based on the classic theme you may encounter other errors:

• Top-level selectors may not contain the parent selector "&"

• compound selectors may no longer be extended

Like the deprecation messages, these errors occur because the Toolkit now uses Dart Sass rather than node-sass. To resolve them, you must use a text editor to perform several steps:

1. In the theme *.scss files, replace all instances of:

   & .configurator-editions {

   with

   .configurator-editions {

2. Similarly, in the _profile-elements.scss file replace:

   &.profile__image {

   with

   .profile__image {

3. Open the assets/css/theme/component/_button.scss file and add these lines of code after the &.is-active declaration:

       &--is-active {
           color: $BUTTON_COLOR_SELECTED;
           text-shadow: 0 1px 0 $BUTTON_TEXT_SHADOW_SELECTED;
           border-color: $BUTTON_BORDER_SELECTED;
           background-color: $BUTTON_BACKGROUND_SELECTED;
           box-shadow: inset 0 2px 6px -1px $BUTTON_BOX_SHADOW_SELECTED;
       }           

4. Open the assets/css/theme/pages/_listing.scss file and replace all instances of:

   @extend .button.is-active

   with

   @extend .button--is-active

Once you have made and saved these changes, the errors should no longer occur.