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

Before you begin

• Complete Getting started before working through this page.

Create your app

Create an app based on the Confluence macro template.

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:

   1
   2
   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:

   1
   2
   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:

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 

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

• src/frontend/index.jsx: Where you write the application with which the user interacts directly.

• manifest.yml: Describes your app. This file contains 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.

  • You’ll notice that the module in the manifest includes a new render: native property. This is how you declare that a module is a UI Kit 2 app.
  • You must include the render: native property for any other UI Kit 2 modules you may wish to add.

• package.json: 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: Information about the app. We recommend updating this as you change the behavior of the app.

• index.jsx: Where you write the src/resolvers/index.jsx function definitions. For more information, see Custom UI Resolver docs.

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.

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:

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

Deploy and install your app

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 your Atlassian product using the arrow keys and press the enter key.

4. Enter the URL for your development site. For example, example.atlassian.net. 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.

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 from the toolbar.
3. Find the macro by name and select it.
4. Publish the page.

Tunneling

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.

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.