The Forge global:ui module is now in Preview, and therefore fully supported. However, it remains under active development and may be subject to shorter deprecation windows. Preview features are suitable for early adopters in production environments.

The global:ui module currently supports only UI Kit (render: native).

Atlassian releases preview features so partners and developers can study, test, and integrate them before General Availability (GA). For more details, see Forge EAP, Preview, and GA.

The global:ui module gives your Forge app its own end-to-end experience within the Atlassian platform. It provides a side navigation bar and a main content area that users access directly from the Atlassian app switcher.

To build this experience, you must use the global:ui UI Kit components.

Manifest structure

To use global:ui, add a global:ui entry to the modules section of your manifest.

1
2
3
4
5
6
7
8
9
10
modules []
└─ global:ui {}
   ├─ key (string) [Required]
   ├─ resource (string) [Required]
   ├─ render (string) [Required - must be native]
   ├─ resolver {} [Optional]
   ├─ title (string | i18n object) [Required]
   ├─ icon (string) [Optional]
   └─ emitsReadyEvent (boolean) [Optional]

Example manifest

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
modules:
  global:ui:
    - key: my-app
      resource: main
      render: native
      resolver:
        function: resolver
      title: My App
      icon: resource:icons;icon.svg
  function:
    - key: resolver
      handler: index.handler
resources:
  - key: main
    path: src/frontend/index.jsx
  - key: icons
    path: icons
permissions:
  content:
    styles:
      - "unsafe-inline"
app:
  runtime:
    name: nodejs22.x
    memoryMB: 256
    architecture: arm64
  id: ari:cloud:ecosystem::app/your-app-id

Properties

Property	Type	Required	Description
`key`	`string`	Yes	A unique key that identifies this module within the app. Must be unique across all modules in the manifest.
`resource`	`string`	Yes	The key of a static `resources` entry that your module will display. See resources for more details.
`render`	`string`	Yes	The rendering method for the module. Must be set to `native`, which enables UI Kit rendering. Custom UI is not supported for `global:ui`. The platform enforces a UI chrome around the module and UI Kit is the public API that lets you control it. To embed custom web content in the main content area, use the `Frame` component inside `<Main>`.
`resolver`	`object`	No	An optional object that specifies a resolver for back-end data access. Set the `function` property if you are using a hosted `function` module for your resolver. Set the `endpoint` property if you are using Forge Remote to integrate with a remote back end.
`title`	`string` or i18n object	Yes	The display name for your app. Shown in the Atlassian app switcher and in the top navigation bar.
`icon`	`string`	No	A reference to a local SVG resource for your app icon, in the format `resource:<resource-key>;<filename>`. Displayed at 24×24px in the sidenav header and 32×32px in the app switcher. Requires a corresponding entry in the `resources` section.
`emitsReadyEvent`	`boolean`	No	Defaults to `false`. When `true`, the platform continues to show the initial loading screen with your app logo until your app code calls `view.emitReadyEvent()`. Use this when your app needs to load data or finish rendering before users see it. If your app doesn't call `view.emitReadyEvent()`, the loading screen is removed after a default timeout of 10 seconds.

i18n object

To provide localized titles, use an i18n object:

1
2
3
4
5
title:
  i18n:
    default: My App
    es: Mi aplicación

Show the loading screen until your app is ready

The following example keeps the loading screen visible until the app calls view.emitReadyEvent():

1
2
3
4
5
6
7
8
9
10
11
12
13
modules:
  global:ui:
    - key: my-app
      resource: main
      render: native
      resolver:
        function: resolver
      title: My App
      emitsReadyEvent: true
  function:
    - key: resolver
      handler: index.handler

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
import React, { useEffect, useState } from "react";
import ForgeReconciler, { Text } from "@forge/react";
import { invoke, view } from "@forge/bridge";

const App = () => {
  const [summary, setSummary] = useState();

  useEffect(() => {
    const loadData = async () => {
      try {
        setSummary(await invoke("getSummary"));
      } catch (error) {
        console.error("Failed to load summary:", error);
      } finally {
        // Notify the platform even if loading fails, so the loading screen is removed.
        await view.emitReadyEvent();
      }
    };

    loadData();
  }, []);

  return <Text>{summary ?? "No summary available."}</Text>;
};

ForgeReconciler.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
);

Icon example

The following example configures an icon:

1
2
3
4
5
6
7
8
modules:
  global:ui:
    - key: my-app
      icon: resource:icons;icon.svg
resources:
  - key: icons
    path: icons # directory containing icon.svg

Compatibility

Global modules support the compatibility models described in App compatibility. Choose the model that matches whether your app is installed into an Atlassian app on a site, installed in the unit context, or connected to one or more Atlassian apps.

For an app that is installed into a single Atlassian app on a site, you don't need to declare app.compatibility:

1
2
3
app:
  id: ari:cloud:ecosystem::app/your-app-id

For a Global App installed in the unit context with no Atlassian app links, declare an empty compatibility object:

1
2
3
4
app:
  compatibility: {}
  id: ari:cloud:ecosystem::app/your-app-id

For a Global App installed in the unit context with optional Atlassian app links, set each Atlassian app to required: false:

1
2
3
4
5
6
7
8
app:
  compatibility:
    jira:
      required: false
    confluence:
      required: false
  id: ari:cloud:ecosystem::app/your-app-id

For a multiple-app compatible app with a required Atlassian app, set one Atlassian app to required: true and any additional Atlassian apps to required: false:

1
2
3
4
5
6
7
8
app:
  compatibility:
    confluence:
      required: true
    jira:
      required: false
  id: ari:cloud:ecosystem::app/your-app-id

For guidance on choosing a compatibility model, see App compatibility.

Access your app

Users access the global:ui module from the site-level app switcher. The app launches on an existing site hostname using the following URL format:

1
2
{site-hostname}/apps/{installation-id}