Skip to main content

Migrating from TDS to Allium

This document aims to help you upgrade an existing application which uses TDS to use the new Allium Design System. It gives an overview of the requirements and approaches for upgrading. For installation and usage guidance see the Beginner's guide.

Prerequisites​

  • Node 14 minimum support We test all UDS and Allium code against node v14 and v16 only. If you are currently using Node v12 we strongly recommend you upgrade anyway, as it will soon be out of maintenance
  • React 17 Allium is only compatible with React 17. TDS is compatible with both 16 and 17 so we suggest you upgrade to 17 first, and then upgrade to UDS afterwards
  • React Router v5 or above Allium Link components are only tested with React Router v5 and v6. If you are using an older version of React Router it is likely you will still be able to use Allium, but we won't be able to offer the same level of support.
  • Browser support is defined by our browserslist config (learn more about browserslist here). This package is also published to npm and teams are encouraged to reuse this config when building with UDS and Allium. Note that this means No IE 11 support. IE 11 officially reaches end-of-life on June 15 2022.
  • Compilers, Transpilers, and Bundlers We use ES2020 in our source code and in transpiled modules. This works fine with all modern transpilers and bundlers (e.g swc, babel). However older tooling which relies on acorn v6 (for example webpack v4) won't work out of the box with Allium. If you are using an older bundler, we recommend upgrading your tooling before upgrading to use Allium. If that is not an option, you may need to transpile @telus-uds-scoped packages using something like babel-loader, and set a target that matches the ECMAScript version supported by your tooling. Feel free to reach out to the Allium team if you need any help with this.

Compatibility​

Allium has been rebuilt from the ground up using new technologies. As such there will be significant breaking changes compared to TDS. However, the team has made a concerted effort to minimise these changes, using APIs and idioms common in TDS wherever possible. The set of components offered by Allium is likewise inspired by TDS and the overwhelming majority of these components will have an extremely similar API to their TDS counterparts. Below we outline a few areas which are likely to involve some rework when upgrading to Allium.

Use of React Native​

UDS, and therefore Allium, uses React Native to build cross-platform components. React Native can be used on the web via React Native Web. This enables re-use and consistency across platforms, the cost is that it introduces a layer of abstraction between web primitives (DOM elements, CSS etc) and React code. This is similar to how most component libraries work, including TDS, in that it is not possible to directly manipulate the HTML and CSS generated by the component. However if you are currently relying on TDS elements rendering a particular HTML structure or element, you may need to refactor your code to work with Allium.

Another potentially surprising feature of React Native for web developers is that it uses flexbox by default, and defaults to columns, not rows. This is abstracted in all Allium React Native components, however some components may expect to be rendered in a flex container. Where this is the case we have made an effort to call this out in the documentation.

Themes and variants​

Allium leverages the UDS theming mechanism to style UDS Base components. This theming mechanism allows for unlimited visual "variants" of a component. These components accept a variant prop which controls which variant styles are applied. So whereas a typical TDS component might have looked something like:

<MyComponent size="small" priority inverse ... />

In Allium these variant props are typically grouped into a single object.

<MyComponent variant={{size:"small", priority: true, inverse: true}} ... />

Strategy​

You can choose to upgrade to Allium all at once, or on a component-by-component basis, or on a page-by-page basis.

All-at-once​

This is the easiest method for small codebases, as you will not need to worry about visual inconsistency between Allium and TDS. It is only feasible for smaller applications where most active development can pause for the duration of the upgrade.

Component-by-component​

From a technical point of view, Allium can be used alongside TDS without any issues. All Allium styles are completely self-contained and don't require any additional CSS reset. However from a product point of view this is not desirable as the UI will look disjointed. This approach could work well for applications where relatively few TDS components are used (mostly custom UI) and/or where the UI is not customer-facing.

Page-by-page​

This approach mitigates the problem of mixing Allium with TDS by ensuring each page is consistent within itself. This approach will scale to a larger, customer-facing application but will require extra developer effort for the duration of the transition versus an all-at-once approach.