Rate this page:

This page describes a Forge preview feature. Preview features are deemed stable; however, they remain under active development and may be subject to shorter deprecation windows. Preview features are suitable for early adopters in production environments.

We release preview features so partners and developers can study, test, and integrate them prior to General Availability (GA). For more information, see Forge release phases: EAP, Preview, and GA.

This tutorial will walk you through creating a sample Forge app for Confluence using UI Kit 2.

Before you begin

Make sure that you have the following dependencies installed to work with UI Kit 2:

Create your app

Create an app based on the Confluence macro template.

When you create a new app, Forge will prompt you to set a default environment. In this tutorial we use the development environment as our default. Learn more about staging and production environments.

  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:

    forge create
  3. Enter a name for your app (up to 50 characters). For example, hello-world-app.

  4. Select the UI Kit 2 (preview) category.

  5. Select the confluence-macro template.

  6. Change to the app subdirectory to see the app files:

    cd hello-world-app

confluence-macro template

The app we'll create will display a macro on a Confluence page, with a resource file that provides the contents of the macro.

The confluence-macro template uses Node.js and has the following structure:

├── 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 

Let’s have a look at what these files are:

The resource path also points to the app’s src/frontend/index.jsx file. This is for the Forge CLI to automatically build your resource on deploy, without you having to build it manually.

You should only need to write to the src/frontend/index.jsx file, and src/resolvers/index.js if you choose to include a resolver.

Change the macro title

This app displays content within a Confluence page using a macro. Confluence shows the title of the macro in the quick insert menu when you add the app to a page. Let's change the title to include your name.

  1. In the app’s top-level directory, open the manifest.yml file.
  2. Find the title entry under the macro module.
  3. Change the value of title to Forge app for <your name>. For example, Forge app for Mia.

Your manifest.yml file should look like the following, with your values for the title and app ID:

    - key: hello-world-macro
      resource: main
      render: native
        function: resolver
      title: Forge app for Mia
    - key: resolver
      handler: index.handler
  - key: main
    path: src/frontend/index.jsx
  id: '<your app id>'

Deploy and install your app

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

    forge deploy
  2. Install your app by running:

    forge install
  3. Select your Atlassian product using the arrow keys and press the enter key.

  4. Enter the URL for your development site. For example, View a list of your active sites at Atlassian administration.

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

Running the forge install command only installs your app onto the selected product. To install onto multiple products, repeat these steps again, selecting another product each time. Note that the Atlassian Marketplace does not support cross-product apps yet.

You must run forge deploy before running forge install in any of the Forge environments.

View your app

With your app installed, it’s time to see the app on a page.

  1. Edit a Confluence page in your development site.
  2. Select Insert icon from the toolbar from the toolbar.
  3. Find the macro by name and select it.
  4. Publish the page.


Tunneling allows you to see the changes you’ve made to your UI Kit 2 application in real time. It is a development tool that is meant to increase productivity by removing the deployment step during active development of an application.

To run the tunnel, follow these steps:

  1. Navigate to the root of your project (in this case it would be hello-world-app).
  2. On the command line, run forge tunnel.

The Forge CLI will start bundling your resources and once you see the Listening for requests... on the console log, your tunnel has been established.

Once you are done with the development, make sure to run forge deploy to save the changes and make them permanent.

For more information about tunneling, have a read at this page Tunneling.

Distribute apps

After building your app, you can distribute it publicly through the Atlassian Marketplace or just share it privately with your team. See Distribute your apps for more details.

Rate this page: