Skylab SDK best practices

Use the latest version

A significant portion of reported bugs are solved by users upgrading to the latest version. Even if releases don't contain needed features, in many cases there are bug fixes and accessibility optimizations that your users will appreciate.

Report bugs

We depend on our users to help strengthen Skylab SDK by reporting bugs. If you find an issue, you can report the bug on the #skylab Slack channel by following these simple steps:

Click the information icon in your Slack window to open the “Details” pane
Click Shortcuts
Click “Submit a Skylab SDK Bug”

Even if you see an easy way to work around a bug, we still appreciate any report of behavior that does not match expectations. In some cases, there may be a gap in documentation. In others, it may be a bug in the implementation. But in any case, other users will benefit from your bug report.

Don't hack components

If you are provided a design that does not match the behavior described on this documentation site, please first address the mis-match with your UX designer and if necessary, escalate to the #skylab Slack channel. We strongly advise against ever manipulating the internals (CSS or JS) of a Skylab SDK custom element. The custom elements are a black box and are only supported when implemented according to the API described on this documentation site (including usage of utility classes which, for example, apply alternative positioning than the default).

Skylab SDK consumers making changes to the internals potentially brings about a variety of issues, including:

Breaking changes may well be introduced in a future Skylab SDK minor or patch version for unsupported implementations
Accessibility requirements may be over-ridden, exposing the organization to litigation
The user experience across different Avalara apps can become fractured

Engage with the Skylab community

The #skylab Slack channel is a vibrant community of Avalara designers, developers, and other stakeholders. Please engage with your fellow users. If someone asks a question that you have input on, please by all means engage! Community input is in many cases more helpful than input from Skylab SDK maintainers.

Render slots once, hide them conditionally

One of the primary challenges we've had in developing a library that is compatible across numerous front-end frameworks is in managing HTML children. HTML children can fall into a gray area where it is unclear which rendering engine is responsible for them: the app's or the custom element's. This scenario can cause bugs.

A common pattern in front-end frameworks is to render a piece of content conditionally. Unfortunately this pattern produces the aforementioned bug. Instead of following this pattern, slots should be rendered once and only once. If an optional slot must be hidden, it should be done so by conditionally applying the "hidden" class, not conditionally rendering the slot. The content within the slot can be dynamically rendered as necessary, just not the slot itself.

For example, this is the recommended pattern in React to conditionally hide a footer slot in the <s-dialog> component:

  
  function MyReactComponent {
  ...
    return (
      <s-dialog>
        <div slot="header" id="dialog-title">Title</div>
        <div slot="body">Content</div>
        <div slot="footer" class={showFooter ? "" : "hidden" }>
          <button class="secondary small">Cancel</button>
          <button class="primary small">Save</button>
        </div>
      </s-dialog>
    )
  }

Conversely, the following implementation is not recommended and may produce bugs (due to conditional rendering):

  
  function MyReactComponent {
  ...
    return (
      <s-dialog>
        <div slot="header" id="dialog-title">Title</div>
        <div slot="body">Content</div>
        {showFooter && 
          <div slot="footer">
            <button class="secondary small">Cancel</button>
            <button class="primary small">Save</button>
          </div>}
      </s-dialog>
    )
  }

Implement Skylab SDK custom properties in your CSS

We recommend using Skylab SDK CSS custom properties throughout your codebase so that if we update any of those parameters (e.g. changing a hex value within the color palette), they will be reflected in the application.

Use a single source of truth for the Skylab SDK version

We recommend considering the assetPath and version from the Artifactory package as your source of truth for the active version of Skylab SDK bundle. When updating to new versions, the version in your package.json will be the only one in need of updating. Please ensure the @avalara/skylab-sdk package exists in your dependencies rather than devDependencies in order to use the recommendation described below.

If using server-side rendering (e.g. Handlebars.js), we recommend a pattern similar to the following (this comes pre-configured with App Archetype):

// server.js const skylabSdk = require('@avalara/skylab-sdk') res.locals.skylabSdkAssetPath = skylabSdk.assetPath;

Unit testing Skylab SDK components

Node version

Node 12+ is required to run unit tests.

<script> tag

By default, unit tests in your codebase will indicate the existence of a Skylab SDK custom element, but without pulling the Skylab SDK bundle into your app, the behavior of that custom element will not be testable.

If you are able to implement a <script> in your unit testing framework's template to pull in external resources, we recommend doing so according to our Installation instructions.

Please reach out on the #skylab Slack channel if there are any unresolved issues around unit testing.