Build your first app

Welcome to your first hands-on challenge. This tutorial will guide you through creating your first Forge app using UI Kit, Atlassian’s framework for building app interfaces that look and feel native.

The tutorial will cover the following Forge concepts:

• Modules: confluence-space-page or jira-project-page
• UI Kit: Text, Heading, Lozenge
• Fetch API: requestConfluence or requestJira
• Forge Bridge: invoke, view

The 'Hello World' App

The Hello World App is designed to show you the basics of building a Forge app. You can choose to build your first app for Jira or Confluence—the tutorial structure is the same, but the product-specific modules differ. Select the product that best aligns with your goals or interests.

About the tutorial

Approximate time needed: 15-30 minutes

Suggested Skills: Basic understanding of Javascript, React is recommended.

This tutorial has instructions for creating either a Jira app and a Confluence app. Look out for the tabs in each section for the correct instructions for your project.

First, you'll use the Forge CLI to create a new app based on one of the many available templates, you will then customise the app and add a new module. You will also learn how to build and deploy the app, and install it onto your confluence developer test site.

Next, you'll customise your app further by accessing application context data via both the front and back end. You will also learn how to automatically deploy the app, and troubleshoot the app using console logging.

Finally, you'll personalise your app by replacing 'world' with the name of the current user, which you will get from the Confluence or Jira API. You'll also learn how to use the Forge CLI to automatically detect and fix permissions errors.

Before you begin

Before you start creating your app, ensure you've prepared by completing the steps outlined in Preparing for your development environment.

If you have time, you may also want to review Essential Knowlege which will explain where to find all the essential forge knowledge, and more importantly where to go to ask for help if you get stuck.

If you get stuck along the way, you can review the source code at bitbucket.com: Forge quest solutions.

Create your app

About the Forge UI Kit app templates

The app you created above used either the Confluence Space Page or Jira Project Page UI Kit template.

The Forge UI Kit templates use Node.js and typically have the following structure:

1
2
.
├── README.md
├── manifest.yml
├── package-lock.json
├── package.json
└── src
  └── frontend // front-end code goes in this folder
    └── index.jsx
  └── resolvers // back-end code goes in this folder
    └── index.js
  └── index.js // this exports the resolver functions to the top level directory 

Lets have a look at these files and directories a little more closely:

• src/frontend/index.jsx: contains the application the user interacts with directly
• manifest.yml: contains the description of your app, including the name and ID of the app, the app permissions, and the modules the app uses. To learn more about the manifest.yml file, see Forge manifest documentation.
• package.json: contains the app’s Node.js metadata. See the Node documentation for more information.
• package-lock.json: Records the version of the app’s dependencies.
• README.md: contains information about the app. We recommend updating this as you change the behavior of the app.
• src/resolvers/index.js: contains the applications backend functions, the functions are then defined in index.js and can be invoked from the frontend using the UI bridge method. For more information, see Custom UI Resolver docs.
• index.js: Where you write the src/resolvers/index.js function definitions. For more information, see Custom UI Resolver docs.

Explore the manifest.yml

1
2
modules:
  confluence:spacePage:
    - key: my-first-quest-hello-world-space-page
      resource: main
      resolver:
        function: resolver
      render: native
      title: Charlie's first Confluence quest
      route: hello-world
  function:
    - key: resolver
      handler: index.handler
resources:
  - key: main
    path: src/frontend/index.jsx
app:
  runtime:
    name: nodejs22.x
  id: '<your app id>'

Deploy and install your app

To use your app, it must be installed onto an Atlassian site. The forge deploy command builds, compiles, and deploys your code; it'll also report any compilation errors. The forge install command then installs the deployed app onto an Atlassian site with the required API access.

1. Navigate to the app's top-level directory and deploy your app by running:

   1
   2
   forge deploy
   

2. Install your app by running:

   1
   2
   forge install
   

3. Select confluence using the arrow keys and press the enter key.
4. Enter the URL for your Atlassian development site. For example example.atlassian.net. You can view a list of your active sites at Atlassian administration

Once the install complete message appears, your app is installed and ready to use on the site specified. You can delete your app from the site by running the forge uninstall command.

About updating your app installation after changes

Once your app is installed, it will automatically pick up all minor app deployments so you don't need to run forge install every time you make a change. Minor deployments are changes that don't modify the app permissions in the manifest.yml file.

To deploy minor changes to your developer site, or bitbucket workspace run the forge deploy command. The Forge CLI will also detect if a change has been made to your app to modify the apps permissions, and will direct you to update your app installation using the forge install --upgrade command.

View your app

Change how your app looks

In this section, you'll make some changes to the src/frontend/index.jsx to change the appearance of your app by using an additional UI Kit component.

1. Navigate to the src/frontend directory.

2. Open the index.jsx file. The default content of the file is shown below:

   1
   2
   import React, { useEffect, useState } from 'react';
   import ForgeReconciler, { Text } from '@forge/react';
   import { invoke } from '@forge/bridge';
   
   const App = () => {
     const [data, setData] = useState(null);
   
     useEffect(() => {
       invoke('getText', { example: 'my-invoke-variable' }).then(setData);
     }, []);
   
     return (
       <>
         <Text>Hello world!</Text>
         <Text>{data ? data : 'Loading...'}</Text>
       </>
     );
   };
   
   ForgeReconciler.render(
     <React.StrictMode>
       <App />
     </React.StrictMode>
   );
   

3. Modify the import statement at the top of index.jsx to import the heading component,

   1
   2
   import ForgeReconciler, { Heading, Text } from '@forge/react';
   

4. Modify the App return statement to use the <Heading> tags instead of the <Text> tags, so that Hello world! displays as a extra large sized heading,

   1
   2
   <Heading size="xlarge">Hello world!</Heading>
   

   To learn more about the Heading component, you can consult the Forge UI Kit reference docs at https://developer.atlassian.com/platform/forge/ui-kit/components/heading/

5. Save the changes you made to index.jsx.

6. Navigate back to the app's top-level directory, and deploy your changes by running:

   1
   2
   forge deploy
   

7. Once the deployment is complete, refresh your app's space page in confluence to see the changes.

Next step

In the next part of this quest you will customise your app further by accessing application context data via both the front and back end. You will also learn how to automatically deploy your app, and troubleshoot it using console logging.

Continue to Part II