Getting started with global:ui (Preview)

This tutorial walks you through creating your first app using the global:ui module. By the end, you'll have a working global app that appears in the Atlassian app switcher with its own side navigation and content area.

Before you begin

Complete Getting started before working through this tutorial.

Set up a development site

You need an Atlassian site where you can install and test your app.

You can provision a Forge demo development site from the CLI. Demo sites include realistic seeded data and enterprise editions of Jira, Confluence, Jira Service Management, and Rovo.

To provision a demo site before installing an app, run:

1
2
forge site provision

Alternatively, deploy your app and run forge install --demo-site. The CLI reuses your latest active demo site, or offers to provision one if none exists.

Alternatively, create a traditional Atlassian cloud developer site:

1. Go to http://go.atlassian.com/cloud-dev and create a site using the email address associated with your Atlassian account.
2. Once your site is ready, log in and complete the setup wizard.

You can install your app to multiple Atlassian sites. However, app data won't be shared between separate Atlassian apps, sites, or Forge environments.

The following user limits apply to traditional cloud developer sites:

• Confluence: 5 users
• Jira Service Management: 1 agent
• Jira Software and Jira Work Management: 5 users

Create your app

1. Navigate to the directory where you want to create the app. A new subdirectory with the app’s name will be created there.

2. Create your app by running:

   1
   2
   forge create
   

3. Enter a name for your app (up to 50 characters). For example, my-global-app.

4. Select Global (Preview) as the category.

5. Select your template.

6. Change to the app subdirectory to see the app files:

   1
   2
   cd my-global-app
   

Template structure

Your app has the following structure:

1
2
3
4
5
6
7
my-global-app/
├── manifest.yml        # App configuration
├── package.json
└── src/
    └── frontend/
        └── index.jsx   # UI Kit frontend code

manifest.yml

The manifest declares the global:ui module:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
modules:
  global:ui:
    - key: my-app
      resource: main
      render: native
      title:
        default: My App
      resolver:
        function: resolver
app:
  id: ari:cloud:ecosystem::app/<your-app-id>
  runtime:
    name: nodejs22.x
resources:
  - key: main
    path: src/frontend
    tunnel:
      port: 3000

Key parts of the manifest:

• global:ui module — Defines your app's entry point with a title and resource.
• resources — Points to your frontend code.

For full details, see the global:ui module reference.

Frontend code

The frontend uses the Global, Sidebar, and Main components to build the app layout:

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
import React from "react";
import ForgeReconciler, {
  Global,
  Sidebar,
  LinkMenuItem,
  Main,
} from "@forge/react/global";
import { Text } from "@forge/react";

const App = () => {
  return (
    <Global>
      <Sidebar>
        <LinkMenuItem label="Dashboard" href="/dashboard" icon="chart-bar" />
        <LinkMenuItem label="Settings" href="/settings" icon="settings" />
      </Sidebar>
      <Main>
        <Text>Welcome to your global app!</Text>
      </Main>
    </Global>
  );
};

ForgeReconciler.render(<App />);

For icon guidelines and a list of icons to avoid in global navigation, see Using icons.

For all available global:ui components, see global:ui UI Kit components.

Deploy your app

1. Build and deploy your app by running:

   1
   2
   forge deploy
   

2. Install your app by running:

   1
   2
   forge install
   

3. When prompted, select your Atlassian site.

View your app

Once installed, your app appears in the Atlassian app switcher. You can also access it directly using the following URL format:

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

To find your installation ID, run:

1
2
forge install list

Next steps

• global:ui module reference — Learn about all manifest properties including title, icon, and resolver.
• global:ui UI Kit components — Explore the full set of components for building your app's navigation and content.
• Add custom content using Frame — Embed a Custom UI resource in your app and wire up sidebar navigation using view.createHistory().