4.32.2

Migration Guide

Guidelines for migrating to V4

Summary

In the transition from v3 to v4, several enhancements have been incorporated, accompanied by the removal of unused components for improved efficiency. Additionally, certain CSS and JS scripts have been renamed for better organization and clarity.

In addition to these changes, a significant modification involves the discontinuation of the standalone @avalara/skylab-react package. Instead, a React wrapper is now integrated as an integral component of the core package.

Breaking changes V3 -> V4

aui-ie-banner

  • The aui-ie-banner component is no longer supported.
  • There is no support for the IE browser.

aui-content-switcher

  • The aui-content-switcher component is no longer supported.

custom-properties.css

  • custom-properties.css is no longer published as a separate file. These custom properties are defined in the main stylesheet.
  • customPropertiesCssUrl is not available as an export from the Artifactory package's index.js as it is already defined in main.css file.

v3 suffix

  • Do not use -v3 as a version suffix in any file name. For instance, skylab-sdk-v3.js will become skylab-sdk.js in v4.
  • Updated asset paths from /v3/<version>/ to simply <version>/.

Latest version

  • <assetsPath>/latest now represents the most recent version, rather than the latest version of v2.

Guidelines for migrating to V3

Summary

Skylab SDK components are now being implemented using Stencil.js instead of HyperHTML (reasons for making the switch can be found in our Web Component framework research wiki). The change in frameworks has resulted in a better developer experience when creating and updating Skylab components, which will make inner-source contribution easier.

Although the look and functionality of Skylab components are unchanged in V3, there have been some changes to component APIs. CDN asset files (JS and CSS) have also been renamed and relocated. Please see detailed instructions below for more information.

Version 3: Installation and use (non-React)

Install Skylab SDK package

npm install @avalara/skylab-sdk@4.32.2

The @avalara/skylab-sdk node module contains useful information, but the main bundle is meant to be brought into your app with the <script> tag as described below. The following are exported from @avalara/skylab-sdk:

  • version
  • assetPath (enables a single source of truth when using server-side rendering for your app's Skylab SDK version)
  • customPropertiesCssUrl

Stylesheet

Scripts

Include both of these before your app code.

Version 3: Installation and use (React)

Install Skylab SDK package

See instructions above, and see Skylab React for usage instructions.

Stylesheet

See instructions above.

Scripts

See instructions above.

Breaking changes V2 -> V3

s-box

  • secondary class styling removed.

s-dialog

  • Specify slot names for all s-dialog children elements (slot="header", slot="body", slot="footer"). Use of the <header> and <footer> tags is no longer accepted.
  • The noscroll attribute is no longer supported.

Icon

  • Removed icons:
    • doc-pdf
    • document
    • document-2
    • document-alert
    • doc-csv-filled
    • doc-pdf-filled
    • folder-2
    • image
    • image-filled
    • pencil

s-input-extended

  • The public value getter is no longer available. It has been replaced with a public getValue() method, which returns a Promise that resolves to the input's value (a string).

s-menu

  • s-menu accepts only <li> children (not a or button).

s-select

  • The public value getter is no longer available. It has been replaced with a public getValue() method, which returns a Promise that resolves to the select's value (single select returns a string; multi-select returns an array of strings).

aui-service-notification

  • aui-service-notification is now restricted to text content (no longer accepts HTML children)

s-tag

  • Provide tag's text content inside a span with slot="content".
  • To add an icon to a tag, use the iconname attribute instead of adding an s-icon inside the tag.

s-toasts

  • persistent prop has been deprecated. Toasts will always be persistent. As part of the effort to ensure Skylab SDK meets accessibility compliance requirements, auto-dismissing toasts must not be used.

s-tooltip

  • Provide tooltip text content inside an element with slot="content".

React components

  • Tag names have changed for React-wrapped custom elements with the s- prefix. The React equivalents of these components were formerly called Alert, Badge, RowExpander, etc. The new tag names are prefixed with S: SAlert, SBadge, SRowExpander, etc. Aui prefixed component tag names are unchanged.
  • The RadioGroup React component tag name has been changed to SRadiogroup.
  • All event handler names have changed. The former naming pattern (onSDismiss, onSSelect, etc.) has been changed to onS-dismiss, onS-select, etc.

Migration strategy

Web Component library

Tag and attribute names have not changed in non-React components, so migration should be fairly simple. See the Breaking Changes section for the complete list of API changes. Do a global search for affected components' tag names within your codebase and make changes individually.

React library

Migration from standalone package

The following applies for migration from the standalone @avalara/skylab-react package to the react component library included in the primary Skylab package via @avalara/skylab-sdk/react. This applies to users migrating from both V2 as well as V3 versions of the @avalara/skylab-react package.

React components are available via a containerRegistry which is initialized at runtime. This change was made to ensure that the version of the react components used will match the version of skylab included on the page. Importing components works the same, however it is important to note that it is now necessary that the skylab custom elements have been registered on the page. See the implementation notes on the React usage page. Previously it was possible for the bundle built with @avalara/skylab-react to include an obsolete version of skylab components even when the page itself was including the latest version of the skylab script. 

  /* Old way */
  // import { Alert } from "@avalara/skylab-react"; // V2
  // import { SAlert } from "@avalara/skylab-react"; // V3
  // import type { TabItem } from '@avalara/skylab-react';

  /* New way */
  import { SAlert } from "@avalara/skylab-sdk/react"
  import type { TabItem } from '@avalara/skylab-sdk';

If your app is using typescript, it may be necessary to use a bundler for client module resololution. 


  // tsconfig.json
  "compilerOptions": {
    "moduleResolution": "bundler",
    "module": "esnext",
  }

Migration from V2

When migrating from V2, it will also be necessary to update almost all Skylab tag names. One way to do this is to search/replace V2 component opening/closing tags (e.g. search "<Alert", replace with "<SAlert"). Another way to approach this is to use import aliases in order to continue using V2 tag names in your code: 

import { SAlert as Alert } from "@avalara/skylab-sdk/react";

render() {
  return <Alert status="warning">Alert text here</Alert>
}

Event handler names can easily be changed with a regex find/replace. Search for /\bonS([A-Z])/ (make sure you are using the case-sensitive setting if using a find/replace panel in your code editor) and replace with /onS-\l$1/.

Component-specific breaking changes apply to React components as well as Web Components.

React 19 and Above Compatibility

Although React 19 adds support for custom elements, there are some Typescript issues that arise when using Stencil components as custom elements. Continue to use the React wrapper package (@avalara/skylab-sdk/react) for now, and we will update consumers when the React wrapper is no longer necessary.

Questions?

The best place to reach out to us is on the #skylab Slack channel.