Identify Forge’s components
10 min
Beginner
By the end of this lesson, you’ll be able to:
- Describe the Forge architecture
- Identify the tools and components required to build a Forge app.
- Define the structure of a Forge app.
- Differentiate between UI Kit and Custom UI for building app interfaces.
- Describe the purpose of the manifest.yml file in a Forge app.
- Explain how the resolver handles backend logic in Forge.
What does the Forge architecture look like?
Forge is a serverless app development platform that simplifies Atlassian app creation. It handles the infrastructure, authentication, and scaling for you. Let’s explore the essential parts of Forge and look at its basic mechanics and how they work together, so you'll be equipped to start developing apps for your Atlassian apps.
👇Click the layers below to learn more about each.
The building blocks of Forge
To build a Forge app, you’ll work with a set of core components that each play a specific role in the app development process. Understanding how these components fit together, from creating your app to deploying it, will help you move quickly from idea to implementation.
👇These are the building blocks of Forge and how they fit into the Forge architecture.
Start with the Forge CLI
Before you can build with Forge, you’ll need to install the Forge Command Line Interface (CLI) on your local machine. This tool is essential for creating, developing, deploying, and managing Forge apps from the terminal.
👇The Forge CLI command list:
The Forge CLI allows you to create a new app, select a template, and then deploy and install your app. The CLI works the same across multiple platforms. Whether you’re on a PC, Mac, or Linux.
Choose and modify templates and modules
When you create a new app with the Forge CLI, you can choose a template that downloads a default app file structure containing modules onto your local machine.
Templates are file structures that serve as starter projects to help you scaffold a basic Forge app. Each template includes example code for a common use case, and typically includes one or more modules and a UI implementation. You can use a template to speed up development and get a working app right away.
Each one contains:
- A sample module
- A matching manifest.yml
- UI code (using either UI Kit or Custom UI)
- The correct folder structure and permissions
👉 For example:
The jira.issuePanel template includes:
- A jira.issuePanel module (this app will appear on Jira work items)
- A UI built with Forge UI Kit.
Modules define where and how your app integrates with an Atlassian app. The Forge platform exposes product extension points in the form of these modules, which describe how the Forge app interacts with apps like Jira and Confluence. Apps can include multiple modules to interact with different product areas. You define modules in the app’s manifest.yml file.
👉 Some examples of modules include:
- Function: this is where an app's behavior is defined.
- Trigger: executes a function when an event occurs. These include scheduled triggers, which invoke functions on a scheduled interval, or web triggers, which invoke functions as a result of an HTTP request.
- Jira issue panel: adds an issue panel to a Jira work item when a configured button is clicked.
👉 For example: In this manifest, a module has been added to insert an additional panel to the Jira work item view.
👇The CLI showing the manifest file with a Jira issue panel.
If you are cooking a dish, then modules are the ingredients list and the step-by-step directions for handling the ingredients, which together form the final product.
There are many different modules and a variety of module types, which means that you can build apps that can do almost anything, like automating workflows, customizing the user interface, extending product functionality, or integrating with third-party systems.
Build the app’s interface
Forge offers two options for building your app’s user interface: UI Kit and Custom UI.
Both run securely in the browser, support React, and are hosted in an isolated environment by Atlassian, leaving you free to focus on building your app’s front end.
The key differences between them come down to flexibility, design control, and performance.
UI Kit is the simpler option. It provides a set of prebuilt components (like buttons, text fields, and tables) that match the look and feel of Atlassian apps. These components are maintained and updated by Atlassian, so your UI stays consistent with the latest product updates. UI Kit is a great choice when you want to build apps quickly, maintain visual consistency, and with not a lot of complexity.
👇UI Kit button and toggle components.
Custom UI, on the other hand, gives you full control over your front end. You can build interfaces using standard web technologies like HTML, CSS, and JavaScript to add your own styling and use any third-party libraries or APIs. This is a better fit for apps with complex user interfaces, or when you need more interactive or branded experiences.
👇Custom UI can use various web technologies to create a complex UI.
In short:
- Use UI Kit when you want a fast, consistent, and low-maintenance solution.
- Use Custom UI when you need more flexibility, interactivity, or control over the user experience.
Configure the manifest.yml file
👇An app's manifest.yml.
In the cooking analogy, the manifest file is the recipe, outlining how the ingredients and directions (modules) are used to prepare the dish.
The manifest is a YAML text file that defines your Forge app and how it behaves. It is the central configuration file for your app.
The manifest defines the different modules, functions, and resources that your app will use to extend the product’s functionalities. This file tells Forge what your app does and how it should behave in the Atlassian environment.
Bridge the front and backend
Resolvers define backend functions in Forge. They must be defined in the src directory of your app, and registered in the app's manifest. Resolvers run securely through the Forge infrastructure hosted by Atlassian.
For apps without a front end (such as Automations), the resolver is where you define the app's logic.
For apps without a front end (such as Automations), the resolver is where you define the app's logic.
If your app does have a front end, resolvers can define application logic you want to run through the backend Forge infrastructure rather than through the browser. This can be useful for asynchronous functions, and is required for some tasks such as interacting with external systems via fetch.
You can access your backend resolver functions from your app's frontend using the Forge bridge invoke method.
How was this lesson?
next lesson
Explore the Forge app building process
- Build an app using Forge
- Create the app
- Develop the app
- Deploy your app
- Install your app