Building packages

This guide is for package developers. It supplements the general development guide with additional instructions to build a package on top of StrataKit.

Define dependencies

List packages that are expected to be installed at most once in the host application as peerDependencies. The installed instances of peer dependencies are shared across the whole application and its packages.

Caution

Version ranges of peer dependencies should be carefully managed to ensure compatibility across all packages in the project. It is important to keep your package compatible with the latest versions of StrataKit to allow downstream consumers to upgrade their dependencies as needed.

@stratakit/mui

To use StrataKit, add @stratakit/mui to your peerDependencies. Additionally, list other non-StrataKit peer dependencies, such as @mui/material, react, and react-dom.

{
  "peerDependencies": {
    "@mui/material": "^9.4.0",
    "@stratakit/mui": "^1.0.0",
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  }
}

Note

Packages don’t need to render the Root component themselves - the host application is responsible for setting up the Root.

@stratakit/icons

To use StrataKit icons in your package, add @stratakit/icons to your peerDependencies, then display them as described in the development guide.

Note

Packages don’t configure the bundler themselves - the host application is responsible for serving StrataKit icons as external SVG files.

@stratakit/foundations

If you are using StrataKit CSS variables or other foundations in your package, add @stratakit/foundations to your peerDependencies to explicitly control the package version.

@stratakit/structures

To use StrataKit structures in your package, add @stratakit/structures to your dependencies.

Set up TypeScript types

Add @stratakit/mui/types.d.ts to your tsconfig file as described in the development guide.

Package versioning

Follow semantic versioning when releasing new versions of your package.

Transitive peer dependencies

Peer dependencies introduce additional challenges when managing dependency versions, especially when dealing with transitive peer dependencies. Package developers should consider the full dependency graph.

For example, since @stratakit/foundations is a peer dependency of @stratakit/structures, a version bump of @stratakit/structures can transitively require a newer @stratakit/foundations in the host application - even when the change looks internal from your package’s perspective.

Updating peer dependencies

To use a newer feature non-conditionally in your package, you may need to update the version of a peer dependency.

StrataKit packages consider version bumps of peer dependencies as a non-breaking change if the host application can upgrade to a newer version without disruption.

Non-breaking changes

These widen the accepted range or bump the minimum version of a range to a newer minor or patch version:

{
  "peerDependencies": {
    "@stratakit/foundations": "^1.0.0"
    "@stratakit/foundations": "^1.0.0 || ^2.0.0"
  }
}

{
  "peerDependencies": {
    "@stratakit/foundations": "^1.0.0"
    "@stratakit/foundations": "^1.1.0"
  }
}

Breaking changes

These block upgrades to newer minor or patch versions, or require a new major version:

{
  "peerDependencies": {
    "@stratakit/foundations": "^1.0.0"
    "@stratakit/foundations": "1.1.0"
  }
}

{
  "peerDependencies": {
    "@stratakit/foundations": "^1.0.0"
    "@stratakit/foundations": "^2.0.0"
  }
}

Migrating from iTwinUI

Consider releasing a new major version of your package when adding support for StrataKit. Otherwise, you may introduce breaking changes for users who are still using iTwinUI without setting up StrataKit.

See Migrating from iTwinUI for more information.