Publishing best practices

These are best practices for developers creating reusable packages for iTwin Studio applications. By adhering to these guidelines, you can ensure your packages are stable, maintainable, and easily integrated across the iTwin.js ecosystem.

1. Use Public iTwin.js APIs Only

Packages meant for iTwin Studio apps must only use public APIs. Public APIs are stable and supported, meaning they are less likely to change in ways that could break your code. Using internal, alpha, or beta iTwin.js APIs can lead to instability because these APIs are still under development and may change when iTwin Studio is automatically updated.

To ensure you are only using public APIs, you can use the iTwin Studio CLI lint command (e.g., see studio-cli apps lint --help). This command will check your code and its dependencies for any usage of internal, alpha, or beta APIs and will fail if any are found. This helps maintain the stability and reliability of your packages.

2. Avoid Registering UI Items

When developing reusable packages, do not register UI items directly with UiFramework, UiItemsManager, or StudioApps.addSidebarButton. UI items include elements like buttons, widgets, and toolbars. Instead, leave the responsibility of registering these UI items to the consumer of your component. This approach provides flexibility, allowing the consumer to decide how, where, and if they should register the UI item based on their specific needs and context.

3. Write cross-platform code

Packages that use iTwin Studio’s StudioApp or StudioHost API’s will only be usable by other iTwin Studio apps. Instead, prefer using more general APIs like IModelApp or IModelHost from iTwin.js. These APIs are designed to be used across different applications, promoting cross-compatibility and reducing the dependency on iTwin Studio-specific functionality. For example, instead of using StudioApp.logInfo for logging information, use Logger.logInfo from iTwin.js.

4. Split larger repos into smaller packages

A monorepo structure is recommended for managing dependencies and separating reusable packages from application-specific code.

Recommended Structure:

.
├── packages/
│   ├── FeatureA/
│   └── FeatureB/
└── apps/
    └── AppName/

In this structure, the packages directory contains reusable packages that can be published to NPM and to the Component Registry. The apps directory contains code specific to your iTwin Studio application. This helps manage dependencies and maintain a clear separation between reusable packages and application-specific code.

5. Use the Component Registry

Hundreds of reusable components that can be used in your iTwin Studio app can be found in the Component Registry. It’s a centralized repository of all Bentley npm packages which highlights packages based on various quality scores like frequency of use and dependencies.

Before creating new features, check the registry to see if an existing component can meet your needs. This practice helps maintain consistency and reduces development time.

If you’ve created components that other developers might be able to reuse, you’re encouraged to add the bentleyComponentRegistry key to your own package.json files with a bit of metadata. Here is an example:

{
  "bentleyComponentRegistry": {
    "components": [
      {
        "displayName": "Component Name",
        "readmeFilename": "docs/readme.md",
        "keywords": ["itwinjs", "cesiumjs"]
      }
    ]
  }
}

Previously, components needed to be manually added to the Component Registry. Now, all @bentley and @itwin packages are automatically included. But adding some metadata to the bentleyComponentRegistry key will significantly improve discoverability and reuse.

For specific details see the Component Registry Wiki.