Version conflicts

⚠️ Note: This page has moved to https://github.com/iTwin/iTwinUI/wiki/Version-conflicts

---

⚠️ Note: This guide was written for iTwinUI-css 0.X and iTwinUI-react 1.X. We have since released iTwinUI-css 1.X and iTwinUI-react 2.X, which we recommend using instead. If that is not feasible, we recommend updating to the very last minor versions of each (i.e. @itwin/itwinui-css@0.63.1 and @itwin/itwinui-react@1.48.1), as there will be no more changes made to them.

Semver and iTwinUI

At the time of writing, @itwin/itwinui-css is still pre-1.0 but @itwin/itwinui-react is at 1.X. Here's what this means in practice:

• For @itwin/itwinui-css:
  • Minor version bumps may include breaking changes.
    • Usually this means a change in some CSS class names or structure; we try to minimize any changes in Sass variables or CSS variables.
  • Caret ranges in package.json do NOT include minor versions. e.g.: @itwin/itwinui-css@^0.44.0 will NOT allow version 0.45.0.
• For @itwin/itwinui-react:
  • The component API is considered stable and no breaking changes are introduced in minor version bumps.
  • Minor version bumps from @itwin/itwinui-css (which include breaking CSS changes) are handled in a way that preserve the React component API.
  • A particular minor version of @itwin/itwinui-react may only be compatible with the exact version of @itwin/itwinui-css that it lists as a dependency.

Managing multiple versions

If your application has multiple dependencies which use iTwinUI, then it can be confusing to keep track of them and you might even see CSS conflicts.

To alleviate this situation, we have a few recommendations for you:

For library/package authors

If your package has a direct dependency on iTwinUI, then your package.json should:

• List @itwin/itwinui-react as a direct dependency with a caret (^) to allow future minor versions.
• NOT list @itwin/itwinui-css as a dependency, even if you are using some variables from it.

- "@itwin/itwinui-css": "~0.44.1"
- "@itwin/itwinui-react": "~1.29.3"
+ "@itwin/itwinui-react": "^1.29.3"

You should design your package in a way that maximizes the use of the stable React API and minimize the use of unstable CSS classes. For example, if you are building a custom alert, then you should use our Alert component, and extend it using a custom className rather than directly using our CSS classes or mixins which might change in the future.

export const CustomAlert = () => {
  return (
-    <div className='iui-alert more-alert-styles'>...</div>
+    <Alert classname='more-alert-styles'>...</Alert>
  );
};

You can still make limited use of Sass or CSS variables from @itwin/itwinui-css when necessary, through the transitive dependency. In the future, we might move these variables into a separate package to offer more stability.

For applications

As more and more libraries are built on top of iTwinUI, it is natural that your application will have multiple such dependencies as well as a direct dependency on iTwinUI.

The most important thing to remember here is that you need to make sure your lockfile only has ONE version of @itwin/itwinui-css and ONE of @itwin/itwinui-react. If the packages built on top of iTwinUI follow the recommendations above, then this should be pretty straightforward as your application is in control of the exact version that's intalled.

If the packages do not make it easy to synchronize to a single version, then you can force it to the version you want using yarn resolutions for yarn v1, npm overrides for npm v8 and later, or npm-force-resolutions for npm v7 and below.

Note: You might need to remove node-modules and reinstall it for resolutions to work.