Rate this page:
This tutorial walks through creating a Forge app to display content on a Confluence page.
Complete Getting started before working through this page.
Note, Forge apps can't be viewed by anonymous users. To use a Forge app, you must be logged in to Confluence.
Create an app based on the Confluence macro template.
Note, Forge provides multiple environments where you deploy the app. This tutorial uses the CLI default, the environment. Learn more about staging and production environments.
Create your app by running:
Change to the app subdirectory to see the app files:
The confluence-macro 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:
This app displays content within a Confluence page using a . 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.
Your 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 13 14 15
permissions: scopes: - 'read:confluence-content.summary' modules: macro: - key: hello-world-app-hello-world function: main title: Forge app for Mia description: Inserts hello world! function: - key: main handler: index.run app: id: '<your app id>' name: hello-world-app
To use your app, it must be installed onto an Atlassian site. The command builds, compiles, and deploys your code, and reports any compilation errors. The command then installs the deployed app onto an Atlassian site with the required API access.
Note, you must run the command before because an installation links your deployed app to an Atlassian site.
Navigate to the app's top-level directory and deploy your app by running:
Install your app by running:
Select your Atlassian product using the arrow keys and press the enter key.
Note: Running the command only installs your app onto the selected product. To install onto multiple products, repeat these steps again, selecting another product each time.
Enter the URL for your development site. For example, example.atlassian.net.
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 command.
With your app installed, it’s time to see the app on a page.
Your hello world app is now installed into your development site. The app should display on the page like the image below.
Note, while your app is deployed to either a development or staging environment, or will appear in your app title. This suffix is removed once you've deployed your app to production.
Once your app is installed, it will automatically pick up all minor app deployments so you don't need to run the command again. Minor deployments are changes that don't modify app permissions in the manifest.yml file. You can deploy the changes onto your developer site by using one of two methods:
Tunneling allows you to speed up development by avoiding the need to redeploy each code change, and by seeing each invocation as it executes. The Forge tunnel works similarly to hot reloading, so any changes you make to your app code can be viewed on your Atlassian site without losing the current app state. You don’t need to run any other commands; you only need to refresh the page.
To use the command, Docker must be set up and running. To learn about Docker, visit the Docker getting started guides. If you don't want to run Docker, you can redeploy your app after each code change with the command.
Once Docker is set up, you can start tunneling by running:
You should see output similar to:
1 2 3 4 5 6 7 8 9 10
Running your app locally with Docker. The tunnel displays your usage from everywhere the app in the development environment is installed. Press Ctrl+C to cancel. Checking Docker image... 100% Your Docker image is up to date. Listening for requests on local port 37363... Reloading code... App code reloaded.
You can now automatically deploy changes to your codebase and install packages, while tunneling. These changes appear on the Atlassian site where your app is installed.
When you are ready to close the tunnel, press Control + C.
Note, the command only forwards traffic when the user in Jira or Confluence matches the Forge CLI user. For security reasons, you can’t see the traffic of other users.
In the next tutorial, you'll learn how to make API calls to Confluence using Forge. This tutorial uses the , so make sure you are familiar with using this command.
Rate this page: