Frontend Development

In general, Extensions don't necessarily have to provide a frontend as they are optional. Most times though, Extensions should provide a frontend for configuration or interaction with the business logic.

External Frontend vs. Frontend Fragment

In mStudio, there are two main ways to implement and connect a web based frontend for your Extension. External frontends operate independently of mStudio by being opened in a new tab. Frontend Fragments offer a way to integrate chunks of frontend directly into mStudio. In general, these two approaches are not mutually exclusive. An Extension can use both at the same time.

Here is a brief comparison of them, showing the main differences:

	External Frontend	Frontend Fragment
How it works	Opens in a new tab or window	Directly embedded inside mStudio using an iframe
Technology and design	freedom to choose any technology stack and design you like	Built using the same UI components as mStudio, creating a seamless user experience
When to use	You need full control of your Extension's design and behavior	You aim for tight integration into mStudio while maintaining a consistent look and feel

External Frontends

An external frontend creates an entry point from the mStudio into the Extension, opening as a new tab. Using an external frontend, you have complete freedom to choose any technology stack and design you like for your Extension.

You should use an external frontend, if your Extension's frontend can't be built using flow components, or the user should be able to open the Extension without opening the mStudio.

Defining an external frontend enables the use of single sign-on via Access Token Retrieval Key (ATReK).

Configuration

The external frontend is configured as a URL, pointing to the frontend that should be opened in a new tab. This configuration supports templating. For more information, see templating of configuration values. The external frontend is configured in the Extension definition under externalComponents.frontends. For more information, see Extension reference.

Using the ATReK

You have to define the following placeholders in the URL to use the single sign-on feature via ATReK:

• accessTokenRetrievalKey
• userId

The Extension then can extract the ATReK and the user ID from the HTTP call and exchange it for an access token. For more information, see using an Access Token Retrieval Key.

Using the context of the user inside mStudio

You can also use the external frontend to use the current user context of the mStudio in the Extension. This can make sense if a user enters the Extension from a specific project, and the Extension should display said project.

Useful placeholders in the URL for internal routing are:

• apiVersion - API version of the external frontend url template. In the beginning always v1. For more information, see API versioning
• contributorId - The ID of the contributor in UUID format
• extensionId - The ID of the Extension in UUID format
• extensionInstanceId - The ID of the Extension Instance in UUID format
• context - The kind of Extension context, the Extension Instance was added to
• contextId - The ID of the Extension context, the Extension Instance was added to
• userId - The ID of the user that is currently using the Extension
• accessTokenRetrievalKey - The AccessTokenRetrievalKey, commonly called ATReK, of the user. Can be used by the Extension Instance to perform Authentication via ATRek

Example

https://myextension.com/:apiVersion/frontend?atrek=:accessTokenRetrievalKey&userId=:userId&projectId=:contextId

Frontend Fragments

The configuration of frontend fragments serves to integrate an Extension’s frontend directly into predefined anchors within the mStudio. This is particularly useful when the Extension’s frontend should be seamlessly integrated into mStudio to provide the feel of a native feature.

Frontend fragments are configured on an Extension. More detailed information can be found in the Extension reference.

Frontend Fragments are embedded into mStudio via an iframe. This iframe is not rendered directly in the visible area of the page. Instead, a remote architecture that mirrors web components rendered inside an iFrame as React components into mStudio is used. Therefore, development cannot happen entirely locally, yet - you must use an mStudio Instance with an installed Extension as the entry point. This approach ensures a consistent user experience and enables features such as overlays.

Custom components and CSS cannot be used. To develop a frontend fragment, Flow Remote Elements must be used.

Since frontend fragments are embedded via an iframe and Safari in particular is restrictive with third-party cookies, frontend fragments must not rely on cookies. Authentication and session handling are done using Session Tokens and Access Tokens obtained via the Session Token.

While this page provides a general overview of frontend fragments, the documentation on how to develop frontend fragments provides more detailed explanations and examples.

Anchors

mStudio provides well-defined integration points — called anchors — where frontend fragments can be embedded. Each anchor has a unique identifier and must be explicitly configured in your Extension.

⚠️ Currently, each Extension can only attach one frontend fragment per anchor.

Anchor Scope and Limitations

• Extensions installed on projects can only use anchors defined at the project detail level or below.
• Extensions installed on organizations can use anchors at the organization level, as well as all levels below (including project-level anchors).
  • Low level anchors (eg. at project-level) require that the user must be also a member of the organization.

Example: If an Extension is installed on an organization, it may also use project-level anchors. However, if it is installed on a project, it cannot access organization-level anchors.

Supported Anchor Types (in development or available):

• Custom menu items (with associated pages) at any navigation level
• Additional tabs on tabbed views
• Additional sections on sectioned pages

Anchor Discovery (Upcoming Feature)

A feature is currently being developed to visually locate available anchors within mStudio. This will also expose metadata for each anchor — such as required parameters or available context.

For a complete list of available anchors, refer to the Documentation of Implemented Anchors.

Flow Remote Elements

The mStudio only renders components that it knows about. To develop frontend fragments, it is necessary to use Flow Remote Elements. Own components and CSS are not allowed, as the mStudio can only render the components it knows about. Also, frontend fragments should feel like a native feature.

While using React is not mandatory, it is recommended for developing frontend fragments, as this enables the use of Remote React Components. These provide the exact same API as the regular Flow Components, but are designed specifically for use in remote DOMs (frontend fragments).

Authentication and session handling using session tokens

A so-called Session Token is used for authentication and session handling within a frontend fragments. This Session Token can be requested from the mStudio via window messages at any time. It is a JWT containing information about the current user and the Extension Instance. The token is an online token valid for only 60 seconds and should therefore not be persisted.

The mStudio ensures that a frontend fragment does not create a new Session Token with every request, but reuses tokens within the first 40 seconds of their validity.

Session Tokens always include a session ID that is stable for the current session. This ID can be used to identify a user’s session and, for example, to map backend sessions. Session cookies cannot be used, as this does not work in WebKit-based browsers like Safari.

A frontend fragment must always include the Session Token when making requests to its backend. The JWT claims in the Session Token include a key called publicKeySerial, which refers to the serial number of the mStudio public key used to sign the token. The Ed25519 public key can be retrieved from the mStudio API using the operation GET/v2/public-keys/{serial}/. To do this, use the publicKeySerial from the session token as the serial and the purpose session_token.

To simplify signature verification, the public key can be retrieved in SPKI format, ASN.1 serialized, and PEM encoded via the format query parameter.

The backend must validate the session token against the mStudio public key indicated in the token with every request, since the token serves as the user’s authentication credential. This involves decoding the JWT, retrieving the public key via the API, and validating the JWT against the key. A public key with a specific serial is stable and can be cached or persisted.

The session token can also be used in combination with an Extension secret to obtain an access token. For this, the operation POST/v2/authenticate-session-token/ can be used. The resulting access token is also only valid for 60 seconds and should not be persisted.

The entire authentication process is illustrated in the following sequence diagram:

Extension Bridge

The Extension Bridge is a JavaScript library that can be used in frontend fragments to communicate with mStudio. It provides functions to retrieve context parameters and to obtain, decode, and validate session tokens.

For more information, see the Documentation on how to develop frontend fragments.