24. 03. 2026 Sara Ferrari Atlassian

How to Build Your First Forge App for Jira

In the last few months I’ve been delving ever deeper into the Atlassian Forge ecosystem, the serverless platform that allows you to develop apps integrated into Jira, Confluence and other Atlassian cloud products without having to deal with infrastructure, authentication or hosting.

The goal?

Creating my first Forge app from scratch and understanding its complete lifecycle: environment installation, project generation, local testing and final deployment on Jira Cloud.

In this article I’ll share with you the basic steps to doing this and some tips I wish I had known before starting.

How to Prepare the Environment

The first step is to install the Forge CLI, the official tool for creating, testing and deploying apps. You simply need Node.js version 18 or later installed, and then use the command:

npm install -g @forge/cli
forge login

login automatically opens your browser to authenticate with your Atlassian Cloud account. Once the connection is confirmed, the CLI is ready to create new projects.

💡 Tip: make sure you use the same Atlassian account that you’ll use to install the app on Jira, to avoid permission problems later.

Create the First Forge Project

To generate the first app I ran:

forge created

This command offers several templates: from a simple Jira project page to a macro for Confluence, or even a React-based Custom UI app.

After choosing the app type, Forge creates the following project structure:

my-first-forge-app/
├── manifest.yml
├── src/
│ └── index.jsx
├── static/
│ └── icon.svg
└── README.md

The manifest.yml file is the heart of the app: it defines modules, permissions and resources that Forge will need to load.

This is where we declare what the app will do and in what context it will appear within Jira.

Understand the Manifest Structure

The manifest follows Forge’s declarative logic: each module represents an entry point into the app. Here’s an example of a minimal manifest for a Project Page, the most used and intuitive type:

modules:
  jira:projectPage:
    - key: project-page-example
      function: main
      title: "Hello Forge"
      icon: resource:icon;icon.svg

function:
  - key: main
    handler: index.run

resources:
  - key: icon
    path: static/icon

The title (“Hello Forge”) and icon are shown under the “Apps” section in the project menu. By clicking that entry, Jira opens a new internal page that loads the content defined in the src/index.jsx file, for example:

import ForgeUI, { render, ProjectPage, Text } from "@forge/ui";

const App = () => {
  return (
    <ProjectPage>
      <Text>Hello this is my first forge app</Text>
    </ProjectPage>
  );
};

export const run = render(<App />);

Testing Locally with Forge Tunnel

One of the most useful features of the CLI is the tunnel, which allows you to connect your on-premises app directly to Jira Cloud and see logs in real time.

forge tunnel

Every change in the code is applied immediately, allowing for a rapid and interactive development cycle.

⚠️ Note: If the tunnel doesn’t connect, check that the account is authenticated with forge login and that the project points to the correct environment.

Deploy and Installation

When the app is ready to test, just use these two commands:

forge deploy
forge install

deploy uploads the code to the Forge Cloud infrastructure, while install adds the app to your Jira instance, where it will be immediately available in the “Apps” menu.

Lessons Learned

During this first project, I learned some good practices:

Version from the start: integrate Git into the project, so that every change is tracked
Declare only necessary scopes: Forge requires that each permission be explicitly defined in the manifest
Take advantage of the tunnel: it’s the most useful tool for rapid debugging and testing
Organize resources and functions well: Forge validates the structure, so a wrong directory can block the deployment

These Solutions are Engineered by Humans

Did you find this article interesting? Does it match your skill set? Our customers often present us with problems that need customized solutions. In fact, we’re currently hiring for roles just like this and others here at Würth IT Italy.