note

This document applies to sfb-toolkit@5.x.x and sfb-theme-components@0.0.352 or newer. For previous versions risks please see here.

Introduction

While Custom Components allow the creation of new UI elements there are a few important consequences/risks that come with this capability:

No automatic UI library updates

When Custom Components are installed using the sfb-toolkit components command a specific version (according to the toolkit version) of our UI library (@appdirect/sfb-theme-components) is being installed. This means that, unlike themes that do not have Custom Components installed, the UI features available are restricted to those of the UI library version installed. As such, unless the version of the UI library is manually updated (see below risks), new UI features will not be available. The reasoning behind this flow is to ensure theme stability. If new features/Custom Components are added that reuse/build on top of our UI library, those customizations will not be at risk of breaking due to interdependencies when a new version of our UI library is released.

Overriding UI library atoms

By installing Custom Components our UI library (@appdirect/sfb-theme-components) is automatically installed. This allows you to reuse, extend or override the UI Library elements we provide. When overriding our atoms either through JavaScript or CSS it is important to keep in mind that these could cause breaking changes. As such, we strongly suggest to thoroughly test any UI elements which use the overridden atoms.

Manually updating the UI library

When Custom Components are installed, manually updating the UI library by executing sfb-toolkit install @appdirect/sfb-theme-components@version can cause custom components which reuse UI library atoms to break (see above). This occurs because reused atoms are pointing directly to our UI library and updating the UI library will also update the atoms. As such, side effects might occur due to updated atoms behaving the same as in the previous version.