Getting started with global:ui (EAP)

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 cloud developer site

An Atlassian cloud developer site lets you install and test your app on Atlassian apps including Confluence and Jira. If you don't have one yet, set it up now:

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 limits on the numbers of users you can create are as follows:

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

Install the experimental CLI

The global:ui module requires an experimental version of the Forge CLI during the EAP. Install it by running:

1
2
npm install -g @forge/cli@13.1.0-next.4-experimental-9423de1

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 (EAP) 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
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 and the required Atlassian app link:

1
2
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
  compatibility:
    confluence:
      required: true
resources:
  - key: main
    path: src/frontend
    tunnel:
      port: 4000

Key parts of the manifest:

• global:ui module — Defines your app's entry point with a title and resource.
• compatibility section — Declares Confluence as the required Atlassian app. Users must have Confluence for the app to be installed.
• 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
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="Home" href="/" />
        <LinkMenuItem label="Settings" href="/settings" />
      </Sidebar>
      <Main>
        <Text>Welcome to your global app!</Text>
      </Main>
    </Global>
  );
};

ForgeReconciler.render(<App />);

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/a/{app-id}/e/{env-id}

To find your environment ID, run:

1
2
forge environments list

Next steps

• global:ui module reference — Learn about all manifest properties including title, icon, resolver, and compatibility.
• global:ui UI Kit components — Explore the full set of components for building your app's navigation and content.