apps-frontend-api

Variables

StudioApp

const StudioApp: StudioFrontendApi;

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

Interfaces

FrontendApp

Common entry point format for modular apps. Modular apps are meant to run in the context of a startup app. until 2026.09

Properties

Property	Modifier	Type	Description
`cleanup?`	`public`	() => `Promise`<`void`>	Performs any necessary cleanup before consuming application deactivates. :::caution[Alpha] This API should not be used in production and may be trimmed from a public release. :::
`getProviders?`	`public`	() => `Promise`<`UiItemsProvider`[]>	Get all UiItemsProviders provided by this package. It will be up to the consuming application to register them and unregister them when needed. :::caution[Alpha] This API should not be used in production and may be trimmed from a public release. :::
`initialize?`	`public`	() => `Promise`<`void`>	Performs any startup logic required by packages. Should be called before getProviders :::caution[Alpha] This API should not be used in production and may be trimmed from a public release. :::
`namespaces?`	`readonly`	`string`[]	Get all locale namespaces provided by this package. It will be up to the consuming application to register them and unregister them when needed. :::caution[Alpha] This API should not be used in production and may be trimmed from a public release. :::

ITwin

ITwin provided through onITwinSelected event

Properties

Property	Type	Description
`iTwinId`	`string`	ID of iTwin
`name`	`string`	Name of iTwin

SidebarButtonProps

Navigation sidebar button props.

Properties

Property	Type	Description
`disableReason?`	`string`	Only considered if isDisabled is true. User facing tooltip message displayed when hovering disabled button.
~~`icon?`~~	`IconSpec`	Icon to display in the sidebar. :::caution[Deprecated] to be removed in 2027.03, due to IconSpec being deprecated in appUI. Use iconNode to pass a react component instead. :::
`iconNode?`	`any`	Icon to display in the sidebar. Takes precedence over icon field. If undefined, defaults to a placeholder icon.
`id`	`string`	Unique id among all sidebar buttons.
`isActive?`	`boolean`	Indicates whether the button is currently active. When set to true, the button remains active until the user clicks on another button, or until another button is activated using this flag. Note that setting isActive flag will activate the button without calling button.onClick method. An active button is highlighted in the sidebar to indicate its active state. Defaults to false.
`isDisabled?`	`boolean`	If true, button is disabled. Defaults to false.
`label`	`string`	User facing button label.
`onClick`	() => `void` \| `Promise`<`void`>	Callback invoked when user clicks the entry. Typically, this would be used to activate a custom frontstage.
`onDeactivate?`	() => `Promise`<`undefined` \| `"cancel"` \| `"continue"`>	Provides a callback to be invoked when the user presses another sidebar button that is not the current one.

StudioAppRuntimeInfo

Properties

Property	Type
`productFlavor`	`string`
`productVersion`	`string`
`startupApp`	`object`
`startupApp.config`	`Pick`<`AppConfigJsonSchema`, `"appId"` \| `"gprId"` \| `"displayNameEnglish"` \| `"displayNameKey"`>
`startupApp.version`	`string`

StudioFrontendApi

Extended by

StartupAppsFrontendApi

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.

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

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>

getApiOverrides()

getApiOverrides(): ApiOverrides;

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

Returns

ApiOverrides

getFilePath()

getFilePath(file): Promise<string>;

Gets file path from a file object.

Parameters

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

Returns

Promise<string>

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.

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.

getUrlEnvironmentPrefix()

getUrlEnvironmentPrefix(): UrlEnvironmentPrefix;

Get the current environment prefix iTwinStudio is in.

Returns

UrlEnvironmentPrefix

Note

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

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.

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.

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.

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.

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.

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

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

runtimeInfo()

runtimeInfo(): Promise<StudioAppRuntimeInfo>;

runtime information like product flavor and version etc

Returns

Promise<StudioAppRuntimeInfo>

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>

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>;

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.
}

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>;

Properties

Property	Modifier	Type	Description
`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.
`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. :::
`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. :::
`getConnection`	`public`	() => `undefined` \| `IModelConnection`	-
~~`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. :::
`getCurrentUser`	`public`	() => `undefined` \| `User`	Convenience method to get the current logged in user from the frontend store.
`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.
`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. :::
`onITwinSelected`	`readonly`	(`listener`) => () => `void`	Fires when iTwin is selected either through header dropdown or from iTwin route
`onUserPreferencesChanged`	`public`	(`listener`) => () => `void`	Fires when user preferences are modified by user.
`removeSidebarButton`	`public`	(`id`) => `boolean`	Removes an existing sidebar button. Note: does not deactivate active frontstages or do any “cleanup” other than removing the button.
`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"`
`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" });`

UserPreferenceObject

UserPreference schema object.

Indexable

[name: string]: undefined | JSONSchemaType

References

StudioTelemetry

Re-exports StudioTelemetry

Type Aliases

PushCallback()

type PushCallback = (description?) => Promise<{
  success: boolean;
}>;

Callback invoked when iModel changes should be pushed. Should return true if push was successful, and false if it failed for any reason.

Parameters

Parameter	Type	Description
`description?`	`string`	changeset description.

Returns

Promise<{ success: boolean; }>

UpdateSidebarButtonProps

type UpdateSidebarButtonProps = Required<Pick<SidebarButtonProps, "id">> & Partial<SidebarButtonProps>;