startup-apps-frontend-api

Variables

StudioStartupApp

const StudioStartupApp: StartupAppsFrontendApi;

StudioStartupApp singleton that provides methods for apps to use on the frontend.

Interfaces

BreadcrumbEvents

Breadcrumb click events for the header.

Properties

Property	Type	Description
`onIModelClick`	(`handler`) => `void`	Set handler for iModel breadcrumb click events. Breadcrumb will display the currently active iModel, and it will also be passed to the click handler. If no handler is set, this header breadcrumb will not be clickable. Only one handler can be set at a time. If a new handler is set, the previous handler will be replaced.
`onITwinClick`	(`handler`) => `void`	Set handler for iTwin breadcrumb click events. Breadcrumb will display the currently active iTwin, and it will also be passed to the click handler. If no handler is set, this header breadcrumb will not be clickable. Only one handler can be set at a time. If a new handler is set, the previous handler will be replaced. Typically used to navigate to the iModel selection frontstage.

DownloadOpenBriefcaseReturnArgs

Manages the download of a briefcase. Allows cancellation during briefcase download.

Properties

Property	Modifier	Type	Description
`downloadOpenPromise`	`readonly`	`Promise`<`BriefcaseConnection`>	Promise that resolves when the download completes & briefcase has opened. Throws if briefcase cannot be downloaded or opened. Throws BriefcaseStatus.DownloadCancelled if download is cancelled using DownloadOpenBriefcaseReturnArgs.requestCancel
`requestCancel`	`readonly`	() => `Promise`<`boolean`>	Request cancellation of the download. Downloading a briefcase can be cancelled - successful cancellation will return true. Opening a briefcase cannot be canceled and will return false. Successful cancellation will make DownloadOpenBriefcaseReturnArgs.downloadOpenPromise throw BriefcaseStatus.DownloadCancelled

FrontendAppModule

Extended by

FrontendStartupAppModule

Properties

Property	Type
`activateFrontend`	() => `Promise`<`void`>
`deactivateFrontend`	() => `Promise`<`void`>

FrontendStartupAppModule

Extends

FrontendAppModule

Properties

Property	Type	Inherited from
`activateFrontend`	() => `Promise`<`void`>	`FrontendAppModule`.`activateFrontend`
`deactivateFrontend`	() => `Promise`<`void`>	`FrontendAppModule`.`deactivateFrontend`
`startupOptions`	() => `Promise`<`StudioAppConfigurableOpts`>	-

StartupAppsFrontendApi

Frontend API for startup apps, including functions imported from StudioFrontendApi.

Extends

StudioFrontendApi

Methods

appChannel()

appChannel(channel): string;

Wraps given IPC channel name with a prefix matching the app name. Ensures IPC channel is unique among apps. Not using this wrapper might cause IPC channel name clashes among different apps. Use StudioHost.appChannel to wrap the IPC channel in the frontend.

Parameters

Parameter	Type	Description
`channel`	`string`	unique channel name within your app.

Returns

string

channel name that is unique among loaded apps.

Inherited from

StudioFrontendApi.appChannel

attachRpcInterface()

attachRpcInterface<T>(definition): void;

Attach an RPC interface to the frontend.

Type Parameters

Type Parameter
`T` extends `RpcInterface`

Parameters

Parameter	Type	Description
`definition`	`RpcInterfaceDefinition`<`T`>	RPC interface definition.

Returns

void

Inherited from

StudioFrontendApi.attachRpcInterface

closeConnection()

closeConnection(iModel, closeContext?): Promise<void>;

closes iModel connection

Parameters

Parameter	Type	Description
`iModel`	`IModelConnection`
`closeContext?`	`IModelCloseContext`	-

Returns

Promise<void>

copyToClipboard()

copyToClipboard(text): Promise<void>;

Copies text to the clipboard.

Parameters

Parameter	Type	Description
`text`	`string`	Text to be copied to the clipboard.

Returns

Promise<void>

Inherited from

StudioFrontendApi.copyToClipboard

deleteBriefcase()

deleteBriefcase(iModelId): Promise<void>;

Delete existing briefcase, releasing its briefcase id. If briefcase is still open, this will close it. Note - should be extremely sparingly, e.g. when briefcase is corrupted. All local changes, including those made by other Studio apps, will be lost. until 2026.09

Parameters

Parameter	Type
`iModelId`	`string`

Returns

Promise<void>

downloadAndOpenBriefcase()

downloadAndOpenBriefcase(args): Promise<DownloadOpenBriefcaseReturnArgs>;

Opens a briefcase, downloading it if it does not exist on disk.

Parameters

Parameter	Type
`args`	`DownloadAndOpenArgs`<`DownloadBriefcaseProps`>

Returns

Promise<DownloadOpenBriefcaseReturnArgs>

getApiOverrides()

getApiOverrides(): ApiOverrides;

Get the overrides for specifying which environment iTwin Studio is currently in.

Returns

ApiOverrides

Inherited from

StudioFrontendApi.getApiOverrides

getFilePath()

getFilePath(file): Promise<string>;

Gets file path from a file object.

Parameters

Parameter	Type	Description
`file`	`File`	File object.

Returns

Promise<string>

Inherited from

StudioFrontendApi.getFilePath

getFrontendInitData()

getFrontendInitData<T>(options?): Promise<T>;

Retrieves optional initialization data from the backend to the frontend. Ensure finalizeFrontendInitData() is called in the backend before using this function. The caller should handle potential timeouts by implementing a catch statement.

Type Parameters

Type Parameter
`T` extends `Record`<`string`, `JSONSchemaType`>

Parameters

Parameter	Type
`options?`	{ `timeoutInMS?`: `number`; }
`options.timeoutInMS?`	`number`

Returns

Promise<T>

Initialization data in JSON format as a Promise.

Inherited from

StudioFrontendApi.getFrontendInitData

getITwin()

getITwin():
  | undefined
  | {
  iTwinId: string;
  name: string;
};

Get the iTwin id that is currently open.

Returns

| undefined | { iTwinId: string; name: string; }

The iTwin that is currently open, or undefined if no iTwin is open.

Inherited from

StudioFrontendApi.getITwin

getUrlEnvironmentPrefix()

getUrlEnvironmentPrefix(): UrlEnvironmentPrefix;

Get the current environment prefix iTwinStudio is in.

Returns

UrlEnvironmentPrefix

Note

it returns url prefix like “dev-”, “qa-” or ""

Inherited from

StudioFrontendApi.getUrlEnvironmentPrefix

isBriefcaseCached()

isBriefcaseCached(iModelId): Promise<boolean>;

Checks if the given iModel has a locally cached briefcase (one downloaded using downloadAndOpenBriefcase API’s). Can be used to determine if download indicators should be shown when using downloadAndOpenBriefcase.

Parameters

Parameter	Type
`iModelId`	`string`

Returns

Promise<boolean>

logError()

logError(error, metaData?): void;

Logs an error, with the category being the app name.

Parameters

Parameter	Type	Description
`error`	`string`	Error message.
`metaData?`	`LoggingMetaData`	Additional metadata.

Returns

void

Note

Please use studio-cli helpers migrate-to-logger path/to/src --logCategory category to migrate to Logger apis.

Inherited from

StudioFrontendApi.logError

logException()

logException(exception): void;

Logs an exception, with the category being the app name.

Parameters

Parameter	Type	Description
`exception`	`unknown`	Exception object.

Returns

void

Note

Please use studio-cli helpers migrate-to-logger path/to/src --logCategory category to migrate to Logger apis.

Inherited from

StudioFrontendApi.logException

logInfo()

logInfo(info, metaData?): void;

Logs an info level message, with the category being the app name.

Parameters

Parameter	Type	Description
`info`	`string`	Info message.
`metaData?`	`LoggingMetaData`	Additional metadata.

Returns

void

Note

Please use studio-cli helpers migrate-to-logger path/to/src --logCategory category to migrate to Logger apis.

Inherited from

StudioFrontendApi.logInfo

logTrace()

logTrace(trace, metaData?): void;

Logs a trace, with the category being the app name.

Parameters

Parameter	Type	Description
`trace`	`string`	Trace message.
`metaData?`	`LoggingMetaData`	Additional metadata.

Returns

void

Note

Please use studio-cli helpers migrate-to-logger path/to/src --logCategory category to migrate to Logger apis.

Inherited from

StudioFrontendApi.logTrace

logWarning()

logWarning(warning, metaData?): void;

Logs a warning, with the category being the app name.

Parameters

Parameter	Type	Description
`warning`	`string`	Warning message.
`metaData?`	`LoggingMetaData`	Additional metadata.

Returns

void

Note

Please use studio-cli helpers migrate-to-logger path/to/src --logCategory category to migrate to Logger apis.

Inherited from

StudioFrontendApi.logWarning

onApplicationClose()

onApplicationClose(handler): () => void;

Registers a handler to be called when an attempt has been made at closing the frontend application.

This handler should be used to implement custom logic for handling unsaved changes or other cleanup tasks, which could not be done by simply using the StudioAppConfigurableOpts#promptPushOnClose application configuration option. This handler is executed before the prompt triggered by the #showPushPrompt startup option.

Parameters

Parameter	Type	Description
`handler`	() => `Promise`<`boolean`>	Callback to be invoked when the application is closing. Returning false from this callback will prevent the application from closing.

Returns

A function to unregister the handler.

(): void;

Returns

void

Inherited from

StudioFrontendApi.onApplicationClose

onCloseConnection()

onCloseConnection(callback): void;

Fired when the iModel connection is getting closed. Note that is only called when the iModel connection is closed by Studio, e.g. when switching iTwin, closing the app or via

Parameters

Parameter	Type	Description
`callback`	(`closeContext`) => `Promise`<`boolean`>	Function to be called when the iModel connection is getting closed.

Returns

void

Link

closeConnection. If you manage iModel connections yourself it will not be called.

postFeatureUsage()

postFeatureUsage(featureGuid): Promise<void>;

Posts feature usage to the licensing service.

Parameters

Parameter	Type	Description
`featureGuid`	`string`	Feature guid against which the feature is tracked.

Returns

Promise<void>

Note

Only works in iTwinStudio standard edition in the prod env and iTwinStudio standard edition beta builds for the qa env, and requires a valid GPRID is defined in app.config.json.

postTelemetry()

postTelemetry(telemetry): void;

Sends the telemetry to azure app insights Note: initializeTelemetry needs to be called first from studio-backend-api before using postTelemetry

Parameters

Parameter	Type	Description
`telemetry`	`StudioTelemetry`	telemetry data to send

Returns

void

Inherited from

StudioFrontendApi.postTelemetry

runtimeInfo()

runtimeInfo(): Promise<StudioAppRuntimeInfo>;

runtime information like product flavor and version etc

Returns

Promise<StudioAppRuntimeInfo>

Inherited from

StudioFrontendApi.runtimeInfo

saveUserPreferences()

saveUserPreferences(newUserPreferences): Promise<void>;

Saves the user preferences in the preferences property database.

Parameters

Parameter	Type	Description
`newUserPreferences`	`UserPreferenceObject`	user/overwrite preferences.

Returns

Promise<void>

Inherited from

StudioFrontendApi.saveUserPreferences

setConnection()

setConnection(iModel): void;

iTwin studio holds a single instance of iModel connection at a time. To notify the studio about the change of iModel, call this method on iModel selection and when switching between apps.

Parameters

Parameter	Type	Description
`iModel`	`IModelConnection`

Returns

void

setIgnoreMouseEvents()

setIgnoreMouseEvents(ignore): Promise<void>;

Ignoring mouse messages makes the web contents oblivious to mouse movement, meaning that mouse movement events will not be emitted. See https://www.electronjs.org/docs/latest/tutorial/custom-window-interactions#forward-mouse-events-macos-windows until 2026.09

Parameters

Parameter	Type
`ignore`	`boolean`

Returns

Promise<void>

setITwin()

setITwin(iTwinId): Promise<void>;

until 2026.09 Set the active iTwin id and navigate and skip the iTwin selection page.

Parameters

Parameter	Type
`iTwinId`	`string`

Returns

Promise<void>

Throws

error if the iTwin doesn’t exist.

setLogLevel()

setLogLevel(minLevel): void;

Set the minimum logging level for an app. Logging category will be the app name, which is used by logging functions logException, logError, logWarning, logInfo and logTrace.

Parameters

Parameter	Type	Description
`minLevel`	`LogLevel`	Least severe level at which messages in the specified category should be displayed

Returns

void

Note

Please use studio-cli helpers migrate-to-logger path/to/src --logCategory category to migrate to Logger apis.

setTransparentBackground()

setTransparentBackground(transparency): Promise<void>;

Makes the background for the main window (the window excluding the side and top bars) transparent. This will only work if the AppConfigJsonSchema has window.enablePassthrough set to true.

Parameters

Parameter	Type	Description
`transparency`	`boolean`	true to make the window transparent, false to make it opaque. until 2026.09

Returns

Promise<void>

showOpenDialog()

showOpenDialog(options): object;

Shows a “open file” dialog.

Parameters

Parameter	Type	Description
`options`	`OpenDialogOptions`	Electron open dialog options

Returns

object

closed

closed: Promise<OpenDialogReturnValue>;

Inherited from

StudioFrontendApi.showOpenDialog

showPushPrompt()

showPushPrompt(onPush): Promise<boolean>;

Shows a pop-up dialog prompting the user to push changes. It’s up to the implementation to verify that there is an open iModel with pending changes before showing the dialog.

Typically used before iModel connection is closed, e.g. when switching to a different iModel.

Parameters

Parameter	Type	Description
`onPush`	`PushCallback`	Callback invoked when user clicks on “push”. Should not throw - exceptions will not be handled. If the callback returns `success: true`, the pop-up will be closed. If the callback returns `success: false`, the pop-up will stay open (typically used when “push” action fails, and the user should choose whether or not to retry).

Returns

Promise<boolean>

True if user clicked “push” or “continue”. False if user clicked cancel. until 2026.09

Example

const onPush = async () => {
 try {
  // Inform the user push is starting
  // Push changes
  // Inform the user push was successful
  return true;
 } catch(e) {
  // Inform the user of the failure
  return false;
 }
}

const shouldContinue = await StudioApp.showPushPrompt(onPush);
if (shouldContinue){
 // change active frontstage / close iModel / etc
} else {
 return; // stay on the current frontstage, don't close the imodel.
}

Inherited from

StudioFrontendApi.showPushPrompt

showSaveDialog()

showSaveDialog(options): object;

Shows a “save file” dialog.

Parameters

Parameter	Type	Description
`options`	`SaveDialogOptions`	Electron save dialog options

Returns

object

closed

closed: Promise<SaveDialogReturnValue>;

Inherited from

StudioFrontendApi.showSaveDialog

Properties

Property	Modifier	Type	Description	Inherited from
`addSidebarButton`	`public`	(`props`) => `boolean`	Adds an button to the sidebar navigation. Typically used to allow navigating between different frontstages. If sidebar button already exists, use updateSidebarButton instead.	`StudioFrontendApi`.`addSidebarButton`
`breadcrumbEvents`	`public`	`BreadcrumbEvents`	Events raised when user clicks breadcrumbs in the header. Allows setting custom click handlers. until 2026.09 :::caution[Beta] This API should not be used in production and may be trimmed from a public release. :::	-
`checkInternetConnectivity`	`public`	() => `Promise`<`InternetConnectivityStatus`>	Performs an in-depth check to determine the current internet connectivity status. Recommended to use after http requests throw. until 2026.09 :::caution[Alpha] This API should not be used in production and may be trimmed from a public release. :::	`StudioFrontendApi`.`checkInternetConnectivity`
`createSelectionStorage`	`public`	() => `SelectionStorage`	Creates a new unified selection storage instance. Useful for apps that want to manage their own selection storage separate from the main one provided by iTwin Studio. until 2026.09 - This API is a placeholder until we drop createStorage proxy from @itwin/unified-selection package. :::caution[Alpha] This API should not be used in production and may be trimmed from a public release. :::	`StudioFrontendApi`.`createSelectionStorage`
`getConnection`	`public`	() => `undefined` \| `IModelConnection`	-	`StudioFrontendApi`.`getConnection`
~~`getConnectivityStatus`~~	`public`	() => `0` \| `1`	Get the current connectivity status. :::caution[Deprecated] to be removed in 2027.03, use `checkInternetConnectivity` for in-depth checks, or `NativeApp.checkInternetConnectivity` for quick checks. :::	`StudioFrontendApi`.`getConnectivityStatus`
`getCurrentUser`	`public`	() => `undefined` \| `User`	Convenience method to get the current logged in user from the frontend store.	`StudioFrontendApi`.`getCurrentUser`
`getUnifiedSelectionStorage`	`public`	() => `SelectionStorage`	Returns unified selection storage instance that is managed by iTwin Studio. Removes the need to create a new instance of SelectionStorage and clear it on every iModel change.	`StudioFrontendApi`.`getUnifiedSelectionStorage`
`getUserPreference`	`public`	(`preferenceName`) => `Promise`<`undefined` \| `JSONSchemaType`>	Convenience method to get the user preference value for the given preference name. Uses IPC to get the user preference value from the backend. :::caution[Alpha] This API should not be used in production and may be trimmed from a public release. :::	`StudioFrontendApi`.`getUserPreference`
`onITwinSelected`	`readonly`	(`listener`) => () => `void`	Fires when iTwin is selected either through header dropdown or from iTwin route	`StudioFrontendApi`.`onITwinSelected`
`onNewInstance`	`public`	(`listener`) => () => `void`	Fired when a new instance of the startup app is run.	-
`onUserPreferencesChanged`	`public`	(`listener`) => () => `void`	Fires when user preferences are modified by user.	`StudioFrontendApi`.`onUserPreferencesChanged`
`removeSidebarButton`	`public`	(`id`) => `boolean`	Removes an existing sidebar button. Note: does not deactivate active frontstages or do any “cleanup” other than removing the button.	`StudioFrontendApi`.`removeSidebarButton`
`resolveAssetPath`	`public`	(`pathFromProjectRoot`) => `string`	Resolves the path to the asset using the `studio-app://` url which defines an app-local resource. Example `const path = StudioApp.resolveAssetPath("assets/my-asset.png"); // path === "studio-app://my-app/dist/assets/my-asset.png"`	`StudioFrontendApi`.`resolveAssetPath`
`trackAnalyticsEvent`	`public`	(`event`) => `Promise`<`void`>	Tracks an analytics event using the Amplitude platform. Your app must have a valid GPR ID defined in app.config.json to successfully track events. When naming events, make sure that they are in `Sentence case` like shown in the example below. When providing custom properties, make sure that they are `snake_case` like shown in the example below. Example `trackAnalyticsEvent({ event_name: "Home button clicked", custom_property: "value" });` :::caution[Alpha] This API should not be used in production and may be trimmed from a public release. :::	-
`updateSidebarButton`	`public`	(`props`) => `boolean`	Updates existing sidebar button. Can be used to disable/enable the button or update any properties other than the id. Example `StudioApp.updateSidebarButton({ id: "my-sidebar-button", isDisabled: true, disableReason: "Incompatible frontstage" });`	`StudioFrontendApi`.`updateSidebarButton`

StudioAppConfigurableOpts

Options that an app can provide to customize StudioApp startup. Mostly a subset of IModelAppOptions. until 2026.09

Properties

Property	Type	Description
`aboutDialogAdditionalContent?`	`any`	Additional content to show in the About dialog. until 2026.09 Note: this could likely change or be removed in the future as the requirements are solidified. :::caution[Alpha] This API should not be used in production and may be trimmed from a public release. :::
`headerLogo?`	`any`	Optional logo for the header bar :::caution[Alpha] This API should not be used in production and may be trimmed from a public release. :::
`iModelApp?`	`Pick`<`IModelAppOptions`, \| `"accuDraw"` \| `"notifications"` \| `"accuSnap"` \| `"mapLayerOptions"` \| `"rpcInterfaces"` \| `"viewManager"` \| `"userPreferences"` \| `"tileAdmin"` \| `"toolAdmin"`>	:::caution[Alpha] This API should not be used in production and may be trimmed from a public release. :::
`presentation?`	`object`	:::caution[Alpha] This API should not be used in production and may be trimmed from a public release. :::
`presentation.favorites?`	`FavoritePropertiesManagerProps`	-
`presentation.presentation?`	`Omit`<`PresentationManagerProps`, `"activeLocale"` \| `"activeUnitSystem"` \| `"clientId"`>	-
`presentation.selection?`	`Partial`<`SelectionManagerProps`>	:::caution[Deprecated] to be removed in 2027.03, with itwinjs 5.x. Use `StudioStartupApp.getUnifiedSelectionStorage` from @bentley/studio-startup-apps-frontend-api package instead :::
`previewFeatures?`	`PreviewFeatures`	List of features that can be enabled/disabled https://www.itwinjs.org/reference/appui-react/utilities/previewfeatures/ :::caution[Alpha] This API should not be used in production and may be trimmed from a public release. :::
`promptPushOnClose?`	`boolean`	until 2026.09 if true, the user will be prompted to push pending changes before the briefcase is closed by Studio. User will be able to: 1. Push changes 2. Continue without pushing 3. Cancel the prompt The prompt will be shown: 1. Before Studio closes 2. Before navigating to iTwin Selection frontstage (one provided by Studio) Prompt will not be shown: 1. When an app closes the briefcase or changes the frontstage directly. 2. When Studio restarts due to unhandled exceptions or hot reloading (developer mode). 3. When Studio terminates unexpectedly. 4. If briefcase is not open. 5. If briefcase is opened in read-only mode. 6. If briefcase doesn’t have any pending changes. :::caution[Alpha] This API should not be used in production and may be trimmed from a public release. :::
`rpcManager?`	`object`	:::caution[Alpha] This API should not be used in production and may be trimmed from a public release. :::
`rpcManager.interfaces?`	`RpcInterfaceDefinition`<`RpcInterface`>[]	-
`welcomeBanner?`	`WelcomeBannerOptions`	Configuration for the welcome banner in iTwin Studio. Right now there is no configuration other than enabling/disabling it. Also since there is no learning hub yet, the banner won’t show any primary action for now. This is a starting point for future work regarding announcements. until 2026.09 :::caution[Alpha] This API should not be used in production and may be trimmed from a public release. :::

WelcomeBannerOptions

Options for configuring the welcome banner in iTwin Studio. until 2026.09

Properties

Property	Type	Description
`enabled`	`boolean`	Whether or not iTwin Studio should show a welcome banner on the home page :::caution[Alpha] This API should not be used in production and may be trimmed from a public release. :::

References

DownloadAndOpenArgs

Re-exports DownloadAndOpenArgs

ITwin

Re-exports ITwin

Type Aliases

DownloadBriefcaseProps

type DownloadBriefcaseProps = Omit<DownloadBriefcaseOptions, "syncMode" | "fileName" | "briefcaseId">;

Props for downloading briefcase. Studio fully controls the file name, path and briefcase id. SyncMode will always be “pullPush”.

IModelCloseContext

type IModelCloseContext = any;