Build an App for distribution

Packaging an iTwin Studio App

1. Create New App:

   • Create and build an iTwin Studio App. Follow this tutorial to do so.
   • Specify app icon in app.config.json for shortcut creation.

2. Build and Package: Your template-based iTwin Studio app has a package script in its package.json which can be used for preparing your app for distribution. As a prerequisite to this step, your app must be built via studio-cli first, then you can move to the packaging step:

   1. Execute studio-cli apps build and studio-cli apps package commands to build and package the app.
      • Pass the --dev flag to include source maps (useful for debugging but will increase package size significantly).
      • Pass the --forQARelease flag if releasing to QA. This will keep the authentication.qa properties in app.config.json if they exist.
   2. A .zip file should be created.

Sharing an iTwin Studio App from a ZIP file

Your app is now ready to be shared to other users and they can consume it on their machine where iTwin Studio is installed.

Note that an app in ZIP form must be installed in iTwin Studio before it can be used.

1. Distribution:

   • Take the ZIP file created from the previous step and share with others.

2. Installation for Users:

   • Users can install the app by running iTwinStudio apps install <zip> command.

3. Launch App:

   • Users can click on the desktop shortcut or run iTwinStudio apps run <app-id> command to launch the app.

How to publish an iTwin Studio App to the Marketplace

1. Setup CI/CD Pipelines:

   • See this article on how to start publishing your app from a pipeline

   Note

   GPRID must be set in app.config.json along with relevant authentication scopes before publishing your app since it is used to verify entitlements and enable ULAS. Please see this wiki for further information.

How to automatically update my distributed iTwin Studio App

1. Make Changes:

   • Add new features, fix bugs, or make other code changes.

2. Version Increment:

   • Increment the version number in the package.json file, for example, from 0.0.0 to 0.0.1.

3. Build and Package:

   • Execute studio-cli apps build and studio-cli apps package commands to build and package the updated app.

4. CI & CD Execution:

   • Trigger the CI & CD pipelines. Upon successful execution, the new version should be uploaded to the marketplace.

5. Auto-update Test:

   • Run the installed app. iTwin Studio will download the latest version during the session and install it during shutdown.

Sharing a published iTwin Studio App

1. Distribution:

   • You can still share the ZIP file with others, and they can install the app manually. However, if your app has been successfully published, it might be more convenient for end-users to use the iTwin Studio CLI with the command iTwinStudio apps install <appId>

2. Updates:

   • After a user runs your app, iTwin Studio will check for a newer version available in iTwin extensions marketplace. If an update is available, the user will be notified, and the app will be updated during iTwin Studio shutdown.

Publishing Apps in Advance of Studio Releases

When developing apps that depend on new iTwin Studio features, you can publish your app to the marketplace in advance of an iTwin Studio release by using the minStudioVersion field. This ensures users only receive it when their iTwin Studio version is the same or newer than what is specified by your app.

Configuration

Add the minStudioVersion field to your package.json:

{
  "name": "my-app",
  "version": "2.0.0",
  "studioApp": {
    "minStudioVersion": "1.5.0"
  }
}