Anatomy of an iTwin Studio App

When creating an iTwin Studio App from a template, it’s important to understand its file structure and the different components that make up the App. This section will provide an overview of the different parts and their responsibilities.

File Structure

An iTwin Studio App template typically consists of the following directories and files:

├── __mocks__           // contains pre-defined mocks for unit testing your App
│   ├── @bentley
│       ├── studio-apps-backend-api
│       ├── studio-apps-frontend-api
│       ├── studio-startup-apps-backend-api
│       ├── studio-startup-apps-frontend-api
│   ├── fileMock.js
├── .vscode             // contains settings for easier Visual Studio code development
│   ├── launch.json
│   ├── settings.json
│   ├── tasks.json
├── backend            // contains backend code
│   ├── tests          // contains stubs for backend unit tests
│       ├── index.test.ts
│   ├── index.ts       // the backend entry point
│   ├── tsconfig.json
├── frontend           // contains the frontend code
│   ├── assets         // contains images, json files, etc. accessible via `StudioApp.resolveAssetPath`, e.g. `StudioApp.resolveAssetPath("assets/my-asset.png")`
|       ├── locales    // contains localization files (en, au etc)
│   ├── tests          // contains stubs for frontend unit tests
│       ├── index.test.ts
│   ├── tsconfig.json
│   ├── index.tsx      // frontend entry point
├── dist               // the compiled output that will be published
├── node_modules
├── .npmrc
├── .npmignore         // controls which files are published
├── jest.config.js     // default configuration for unit tests
├── app.config.json    // Application level configuration
└── package.json       // app manifest (App level configuration)
├── README.md

Going over each in more detail:

`.vscode`

We expect our developers to be working with VSCode, our supported code editor. To simplify their effort, this directory contains settings for easier development in Visual Studio Code.

The launch.json file contains settings for launching and debugging, while tasks.json defines tasks that can be run. settings.json contains App level settings such as providing type hints for the manifest file.

`backend`

This directory contains backend code of the iTwin Studio App. The index.ts file is the entry point and should export the following functions:

activateBackend
deactivateBackend
startupOptions

Visit app activation event page to learn more about these functions.

`frontend`

This directory contains frontend code of the iTwin Studio App. The index.tsx file is the entry point and should export the following functions:

activateFrontend
deactivateFrontend
startupOptions

Visit app activation event page to learn more about these functions.

Any assets, such as images or JSON files, are stored in the assets directory, which can be accessed from the App via StudioApp.resolveAssetPath function.

The frontend has access to iTwin.js frontend-devtools package, which provides tools to keep tabs on frontend vitals and perform interactive operations via key-ins. Click here to see usage documentation and available options

`dist`

This directory will contain the compiled code to be published, generated by running dev or build scripts.

`.npmignore`

Configuration that controls which files are included when publishing the iTwin Studio App to the registry.

The following folders/files are the minimal required set for a functioning Studio app:

├── dist               // the compiled output that will be published
├── app.config.json    // Application level configuration
└── package.json       // app manifest (App level configuration)

Source files, node modules, etc. should not be published. You can verify the app contents by running the package command and inspecting the generated .zip file.

`package.json`

This file contains the app manifest, which defines various settings for the iTwin Studio App such as its name, version, etc. The manifest also contains scripts required for building and publishing the App:

"scripts": {
  "test": "jest",
  "build": "studio-cli apps build --backendEntry backend/index.ts --frontendEntry frontend/index.tsx",
  "dev": "studio-cli apps build --watch --backendEntry backend/index.ts --frontendEntry frontend/index.tsx",
  "clean": "rimraf dist"
},

test - run unit tests
build - builds your app for production. Add a --dev argument to build for development (with source map files)
dev - loads your local app into your installed iTwin Studio and provides hot reloading when code files are updated
clean - empties the dist directory
package - creates a bundled tgz package containing studio app
package-dev - creates studio app package with .map files for debugging (if those are available in the dist folder)

iTwin Studio apps must provide additional metadata to control their behavior within by defining a studioApp object field in their package.json file. This is called the app’s manifest. The studioApp object is required in order for your code to be recognized by the iTwin Extension Service as a iTwin Studio App, though there are no required properties in the object at this point. It can remain an empty object, as is provided by the templates.

`app.config.json`

This file contains application-level configuration and is required to launch iTwin Studio. You can configure options such as authentication, offline support, etc. For a complete list of available app.config.json properties, see the schema documentation.

FAQ

Can the provided directory structure be changed?

Yes, you can move files and folders around and rename them as needed, as long as the following is ensured:

the dist directory is preserved for build output. Custom output folder name is currently not supported.
build script is updated to work with the new structure. Options such as backendEntry, frontendEntry, etc. might need updating. See compiling your app for more information.
app.config.json and package.json are required files that must be placed in the root directory.

Are jest and playwright the only supported testing frameworks?

Whilst jest is provided out of the box, app development teams can use other unit test frameworks, e.g. vitest.

iTwin Studio has built-in support for running E2E tests with playwright, and as such it is the recommended framework for E2E testing. Whilst it might be possible to write E2E tests without relying on playwright, iTwin Studio does not provide any guidance on how to do so.