Last updatedFeb 3, 2020

Step 2: Create a Hello World app

This step describes creating, changing, and installing a simple app. The focus is on learning the CLI commands needed to work with an app.

Complete Step 1: Set up Forge before working through this page.

Create your app

Create an app based on the Hello world template. Note, the CLI uses keychain to securely store your login details. If you see a prompt for keychain access when running a command, approve it to allow the CLI to run the command.

  1. Navigate to the directory where you want to create the app. A new directory with the app’s name will be created there.
  2. Create your app by running:
    1
    forge create
    1. Enter a name for your app. For example, hello-world-app.
    2. Select the hello-world template.
    3. Change to the app directory to see the app files.

The CLI displays the following error after running forge create if you don't have the permissions required to create Forge apps:

1
Error: Account does not have app creation enabled...

To get the required permissions, reach out to the #help channel in the Forge Slack and provide the error message and your email address.

hello-world template

The hello-world template uses Node.js and has the following structure:

1
2
3
4
5
6
7
hello-world-app
|-- src
|   `-- index.jsx 
|-- manifest.yml
|-- package.json
|-- package-lock.json
`-- README.md

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

  • index.jsx: Where you write the behavior of the app.
  • manifest.yml: Describes your app. It contains the name and ID of your app, along with the modules it uses. This app displays a macro on a Confluence page and has a function that provides the contents of the macro.
  • 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.

Environments

When creating your app, we also create three environments for you: development, staging, and production. Environments are where you deploy your app. Once an app is running in an environment, you can install it from that environment on to an Atlassian site.

We recommend using the development environment for testing your changes, staging for a stable version of your app, and production as the version of your app that’s ready for use. For the rest of this tutorial you’ll only use the development environment.

By default, the CLI will run commands for the development environment unless you specify another with the --environment flag.

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 Sam Kim.

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

1
2
3
4
5
6
7
8
9
10
11
12
modules:
  macro:
    - key: hello-world
      function: main
      title: Forge app for <your name>
      description: Inserts Hello world!
  function:
    - key: main
      handler: index.run
app:
  id: '<your app id>'
  name: hello-world-app

Deploy and install your app

Deploy your app, with the forge deploy command, any time you make changes to the code. This command builds your code and reports any compilation errors.

Install your app, with the forge install command, when you want to install your app on a new site. Note, once the app is installed on a site, the site picks up the new app changes you deploy without needing to run the install command again.

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

    1
    forge install
    1. Select Confluence as the product.
    2. Enter the URL for your development site (for example, your-domain.atlassian.net).
    3. Important: Authorize your app by opening the URL displayed.

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. Open the quick insert menu and search for your macro title by typing the following into the page:
    1
    /Forge app for
  3. Select the option that includes your name from the quick insert menu.
  4. Publish the page.

Your Hello world app is now installed into your development site. The app should display on the page like the image below.

The app displayed in a Confluence page

Next step

See Step 3: Call a product API to learn how to call a product API from your app.