Set up your local Forge development environment
10 min
By the end of this lesson, you’ll be able to:
- Create a free Atlassian developer site
- Set up your development environment using Node.js
- Install the Forge Command Line Interface (CLI)
- Log in to Forge CLI with your Atlassian API token
- Download your favorite code editor
Create a free developer site
To install and test Forge apps, you’ll need to create a free Atlassian cloud developer site.
We highly recommend using a free developer site for app development/testing instead of your company’s production Jira and Confluence instances. This way, you can experiment freely without risking disruption to real teams or data.
To sign up for a developer site:
- Go to https://go.atlassian.com/cloud-dev and create a site using the email address associated with your Atlassian account.
- Once your site is ready, log in and complete the setup wizard.
Set up your developer environment
To develop Forge apps, you’ll need to install a few tools, including Node.js.
👇Click the tabs below to find setup instructions for your platform and follow the directions for installing Node.js.
Forge developers on macOS should use Node Version Manager (nvm) to configure the environment.
- Select the latest Node.js LTS release by running the following in the terminal:nvm install --ltsnvm use --lts
- Check your Node.js version, run the following in the terminal:node --versionThis command outputs your node version. If a version number is not shown, then the installation failed. Repeat step 1 and look for errors reported in the terminal.
(Optional) Node.js installer: Skip this step if you have successfully completed the previous section.
You can install Node.js using the macOS installer, however, this results in permission errors when working with the Forge CLI. If you must use the installer, you'll need to enable unsafe permissions to use the Forge global package when installing Node.js using this method.
- Install the package.
- Configure npm, permitting unsafe permissions:npm config set unsafe-perm true
Install the Forge Command Line Interface (CLI)
Install the Forge CLI using npm. You’ll install the CLI globally so that the commands can be run across your system.
- Install the Forge CLI globally by running:npm install -g @forge/cli
- Verify that the CLI is installed correctly by running:forge --version
You should see a version number reported in the terminal. If a version number is not shown, then the installation failed. Repeat step 1 and look for errors reported in the terminal.
Log in to Forge CLI with your Atlassian API token
Create or use an existing Atlassian API token to log in to the Forge CLI. The Forge CLI uses your token when running commands.
To create an Atlassian API token:
- Click Create API token.
- Enter a label to describe your API token. For example, forge-api-token.
- Click Create.
- Click Copy to clipboard and close the dialog. This is the only time you’ll be able to view the token, so you may want to paste it into a temporary notepad or text editor.
To log in to the Forge CLI:
- From the terminal or command prompt, run the command forge login.
- You’ll be asked whether to allow Forge to collect usage analytics data:
Allow Forge to collect CLI usage and error reporting information?
Answer Yes to allow Forge to collect data about your app’s deployments and installations (including error data). This helps Atlassian monitor Forge’s overall performance and reliability.
For information about how Atlassian collects and handles your data, read the Privacy Policy. - Enter the email address associated with your Atlassian account and press Enter.
- Enter or paste your Atlassian API token and press Enter.
Download a code editor
To build an app, you will need to write some code, which means that you’ll need a code editor.
We recommend using a code editor that supports JavaScript and provides helpful features like syntax highlighting, autocompletion, and file navigation. Visual Studio Code is a popular, free, and beginner-friendly option available on all platforms.