Getting started with UI

Forge offers two ways to build user interfaces for your apps, UI Kit and Custom UI.

UI Kit is a React-based framework designed for enhancing Atlassian products on Forge. It uses React primitives to render app components natively in our products, which lets your app utilize many of the same native platform components and APIs as our internal teams do.

Custom UI provides a means of building the user interface of an app from scratch. Custom UI runs within an iframe, providing an isolated environment for the app's interface to be displayed.

Product APIs

API requests to products can be made in the frontend using @forge/bridge, typically in your App.js file. Refer to product bridge APIs for the documentation.

Components

User interfaces can be designed using components These are native and reusable building blocks created to streamline the development of user interfaces.

Create a resource

Dependencies

UI Kit expects your app to have the following dependencies installed at the top level directory:

1
2
npm i react@18
npm i @forge/react@latest

File structure

The following directory and UI entry point file should be added to your app /src folder:

1
2
/src
  /frontend
    /index.jsx

React app

React dependencies should be imported, and the Forge render method should be called in the /src/frontend/index.jsx file of your app.

1
2
import React, { useEffect } from  'react';
import ForgeReconciler, { Box, Text } from  '@forge/react';

const App = () => (
  <Box>
    <Text>Hello, world!</Text>
  </Box>
)

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

Manifest definition

A resource should be declared in the app manifest.

1
2
resources:
- key: frontend
  path: src/frontend/index.tsx

Create a resolver

Dependencies

The following dependency should be installed at the top level directory of your app:

1
2
npm i @forge/resolver@latest

File structure

The following directory and UI entry point file should be added to your app /src folder:

1
2
/src
  /backend
    /index.js

Handler

The resolver dependency should be imported, and your resolvers defined in your app /src/backend/index.js file.

1
2
import Resolver from '@forge/resolver';
const resolver = new Resolver();

resolver.define('my-example', async (req) => {
  return {
    data: 'Hello, world',
  }
});

export  const  handler  =  resolver.getDefinitions();

Manifest definition

A function should be declared in the app manifest.

1
2
modules:
  function:
    - key: backend
      handler: index.handler

Attach a UI resource and resolver to an extension point

To integrate UI Kit with an extension point, it needs to be declared on a module. Modules necessitate a resource, resolver, and a render mode to display UI in a product.

1
2
modules:
  macro:
  - key: example
    title: Example Macro
    resource: frontend
    resolver:
      function: backend

Limitations

Although UI Kit utilizes React, it does not rely on React DOM. Consequently, features that depend on the standard browser DOM, such as bespoke HTML, portals, and forwarding refs, will not function.