Compiling your App

About iTwin Studio App builds

You must understand that although an iTwin Studio app looks like a regular node app, it isn’t. An app is supposed to run with iTwin Studio and not as a standalone application, and hence it needs to be built using custom build tools available with iTwin Studio.

iTwin Studio includes a custom build tool in all templates, along with some custom static analysis rules to aid in app development: you might recall that our package.json scripts relied on studio-cli, including one to build the app.

studio-cli is the key tool to build an app. It’s just packaged neatly under build script of your app so you don’t need to worry about raw studio-cli commands to build your app, but it’s essential knowledge that you should know anyway.

The studio-cli apps build command

The studio-cli apps build command is a powerful tool designed to streamline the process of compiling and packaging iTwin Studio apps. This command offers a range of customization options through command-line arguments and configuration files.

Prerequisites

• iTwin Studio
• Enabled developer support
• Node.js v20.x or newer
• pnpm or npm (installed with Node.js)
• Ensure that you are authenticated for Azure Artifacts
• App created as per steps in Creating new iTwin Studio app

Usage

studio-cli apps build [options]

Static analysis

The studio-cli apps build (and studio-cli apps lint) command will ensure your app code and dependencies follow iTwin Studio requirements:

1. Ensure they are compatible with iTwin Studio’s CSP (Content Security Policy).
2. Ensure @internal, @alpha and @beta iTwin.js API’s are not used (via eslint and the @itwin/eslint-plugin no-internal rule)

Note

The no-internal dependency linting can be quite time consuming and memory hungry, so only @bentley and @itwin dependencies are checked by default. To enable it for all dependencies, use the --exhaustiveNoInternal option.

Content security policy (CSP)

Warnings or errors are emitted when a security issue is discovered that conflicts with iTwin Studio CSP. These include but are not limited to the following:

• accessing DOM APIs
• usage of iframes
• usage of data urls

Command-Line Options

Here are some of the key options you can use with studio-cli apps build:

Option	Description
--target <path>	Optional path to the target directory (where the package.json is).
--frontendEntry <path>	Optional path to the entry point for the frontend application.
--frontendTsConfig <path>	Optional path to the TypeScript configuration file for the frontend.
--backendEntry <path>	Optional path to the entry point for the backend application.
--backendTsConfig <path>	Optional path to the TypeScript configuration file for the backend.
--copy <path[]>	Optional array of paths to copy static assets from.
--config <path>	Optional path to a studio.config.json file to customize the build behavior further.
--exhaustiveNoInternal	When specified, lint all dependencies with the no-internal rule, not just @bentley and @itwin packages.
--dev	When specified, output will not be minified and will include source maps.

To get the full list of options you can run:

studio-cli apps build --help

Studio-cli configuration file

Your template based app already has the studio-cli apps build command with all required arguments pre-configured in the package.json for your convenience. However, there is an alternative way to provide arguments for your build command via a configuration file.

The studio-cli apps build command automatically recognizes configuration files named studio.config.json or studio.config.js located at the root of your project.

If your configuration file is located elsewhere or if you prefer to keep multiple configuration files for different purposes, you can explicitly specify the path to the configuration file using the --configoption when running studio-cli apps build.

Sample studio.config.json:

{
  "backendEntry": "backend.ts",
  "frontendEntry": "frontend.tsx",
  "unsafeSkipTsCompile": true,
  "unsafeSkipDependencyAnalysis": true,
  "copy": ["assets"],
  "localeSearchDepth": 0
}

Sample studio.config.js:

module.exports = {
  backendEntry: "backend.ts",
  frontendEntry: "frontend.tsx",
  unsafeSkipTsCompile: true,
  unsafeSkipDependencyAnalysis: true,
  copy: ["assets"],
  localeSearchDepth: 0,
};

To enable VSCode intellisense on iTwin Studio’s config files add the following entry in your .vscode/settings.json project file:

{
  "json.schemas": [
    // ...
    {
      "fileMatch": ["studio.config.json"],
      "url": "./node_modules/@bentley/studio-cli/schemas/studio-config-schema.json"
    }
    // ...
  ]
}

Precedence of options

If you specify an option by using a parameter on the CLI command line, it overrides any value from the corresponding variable in the configuration file.

Actually building the app

Once you are aware of all the options, the final step is simple. Run the following command in your terminal

# if not executed already
pnpm install

pnpm build

You should now see a dist folder created in root of your app with a backend-bundle.js, frontend-bundle.js and .studio-build-info file.