Debugging your app with an iTwin Studio repository clone

Debugging your iTwin Studio App with a local instance of iTwin Studio allows you to test changes to iTwin Studio, iTwin.js, and/or your application simultaneously. Here’s how to do it:

Prerequisites

An iTwin Studio app (or use one of the apps in ./packages/e2e-test-apps).
Familiarity with Node.js and pnpm.
Familiarity with the Node.js Chrome Debugger.
Visual Studio Code (recommended for debugging with launch configurations).

Steps

1. Setup

Clone the iTwin Studio repo.
Run pnpm i at the repo’s root to install dependencies.
Build with pnpm build.

2. Configure Core Versions (Optional)

Using `pnpm overrides`

If you need to specify specific core versions for your dependencies and the core versions are minor or patch upgrades from iTwin Studio’s existing versions (check hoist-versions.json to see what iTwin Studio is currently on), you can use pnpm’s overrides.
Run pnpm override --itwinjs-version x.x.x. Replace x.x.x with the core version you want to test with.
Run pnpm i to re-install dependencies.
Re-build with pnpm build. You may encounter build errors if you are using a version of core that has not been tested with iTwin Studio. Ask the iTwin Studio team if they already have a working branch for the version you want to test with. Otherwise, fix the build issues if possible, and consider submitting a PR to iTwin Studio.
You may get ERROR Found 2 versions of X in lockfile. See log for details. This indicates a peer dependency issue. In some cases, it may be impossible to use the latest versions if dependencies like @itwin/presentation-components don’t support the version of core you’ve selected.

Manually Overriding Package Versions

If you need to override other package versions, modify the pnpm.overrides section in your package.json.
To find the full list of hoisted packages, refer to the hoist-versions.json file located in the ./packages/framework/ directory.

Here is an example of how to override specific package versions manually:

{
  "pnpm": {
    "overrides": {
      "some-package": "1.2.3",
      "another-package": "4.5.6"
    }
  }
}

3. Start your iTwin Studio Application with iTwin Studio

Build your app using the studio-cli apps build --watch command to build your app with source maps. The --watch flag will also watch for any changes to your app’s source code and request iTwin Studio to restart and load the new code.
Navigate to the framework directory:
Terminal window
```
cd packages/framework
```
Use the pnpm start-dev-mode script with your local iTwin Studio app using the --loadLocalApp argument. Absolute or relative paths are supported. Please make sure there are no spaces after the =. For example, here is how you would start the “no-dependency-app” iTwin Studio test app that we use for testing and development:
Terminal window
```
pnpm start-dev-mode ../e2e-test-apps/no-dependency-app/app.config.json --loadLocalApp=../e2e-test-apps/no-dependency-app
```

4. Make Changes and Test

Make necessary changes to iTwin Studio and/or your app. Changes to iTwin Studio should be picked up automatically. If not, exit the app and restart the pnpm start-dev-mode command. Changes to your app should be picked up by the studio-cli apps build --watch command and request iTwin Studio to restart or reload. If not, exit the app and restart the pnpm start-dev-mode command.
If you need to make a change to a dependency of iTwin Studio, you can use pnpm patch. Changes using pnpm patch will always require you to stop the running command, apply the patch, and run pnpm i. Consider contributing changes upstream by making a pull request to the dependency’s repository.

5. Debug iTwin Studio

Using the Node.js Debugger

Open Chrome and go to chrome://inspect.
Configure Chrome to listen for ports 9223 (backend) and 9224 (frontend).
Start debugging with pnpm start-dev-mode-debug. For example:
Terminal window
```
pnpm start-dev-mode-debug ../e2e-test-apps/no-dependency-app/app.config.json --loadLocalApp=../e2e-test-apps/no-dependency-app
```
Replace the path with the path to your app. no-dependency-app is a stub app used as an example.
Reopen chrome://inspect and connect to the respective ports (9223 or 9224).
Use the Chrome debugger to view and set breakpoints:
- Navigate to backend.ts for backend initialization.
- In the Sources panel, find the studio repo and your app’s directory in the left side.
Note: For breakpoints during initialization, use --inspect-brk instead of --inspect.

Using VSCode

Use a launch.json with the following launch configuration:

{
  name: "Launch an App with Local iTwin Studio",
  request: "launch",
  cwd: "path/to/studio/packages/framework",
  runtimeArgs: ["start-dev-mode-debug", "path/to/app/app.config.json", "--loadLocalApp=path/to/app"],
  runtimeExecutable: "pnpm",
  type: "node",
}

Attach to iTwin Studio Backend (port 9223):

    {
      "name": "Attach to iTwin Studio Backend",
      "type": "node",
      "request": "attach",
      "port": 9223, // must match the port set in STUDIO_UTILITY_EXTRA_CLI_ARGS
    },

Attach to iTwin Studio Backend (port 9224):

    {
      "name": "Attach to frontend",
      "type": "chrome",
      "request": "attach",
      "timeout": 30000,
      "port": 9224 // Must match the port set by --remote-debugging-port=9224
    },

6. Building the installer locally (optional)

If you want others to try out the work you’ve done locally, you can build the iTwin Studio installer and send them the exe.
Navigate to ./packages/framework directory, and run:
- ./installer/setup.ps1 in powershell (one time setup only)
- pnpm build-installer.
Installer can then be found in ./packages/framework/out/iTwinStudioInstaller.exe

Integrating the iTwin Studio with your existing repo

Depending on how you want to integrate iTwin Studio with your existing repo, here are a few options/recommendations:

(Recommended) Create a branch in the iTwin Studio repo named with your appId (i.e. git checkout -b appId) or your appId and current iTwin.js version (i.e. git checkout -b appId/4.8.x). This will allow you to persist your overrides so that all of your team members are operating on the same version. In addition, you can “freeze” iTwin Studio for a point in time without worrying about changes to the main branch affecting your app code until you are ready to merge. Finally, this will give you, and the iTwin Studio team, the ability to compare your changes against main.
(Recommended) Have the iTwin Studio repository as a git submodule in your existing repository. Do this if a customized iTwin Studio will always be a dependency of your app. Git submodules ensure version control synchronization between the two repositories, but submodules can be tricky to manage.
Create a .code-workspace file inside your existing repository or as a new repository, containing the iTwin Studio repo and your app’s repository.
Keep iTwin Studio separate. Develop on iTwin Studio only when you have to test out a new feature or bug fix.