A zero-config toolkit for creating fine Forge apps.
The Forge Dev Kit (FDK) is a preconfigured set of libraries and frameworks for developing apps for Atlassian Jira - and soon, Confluence - with ease. The FDK builds on Atlassian Forge, TypeScript, React, Emotion, Next.js, and the Atlassian Design System, plus a number of libraries to glue it all together.
FDK doesn't replace the standard Forge tooling; it instead simplifies the creation of Custom UI-based modules, which can then be used within any (new or existing) Forge app.
Before getting started, make sure that Forge is set up for development.
Creating your FDK module
Create a new FDK module by running
npx @finesoftware/forge-dev-kit create
In the wizard that follows, chose the
Hello world template, and read through any instructions carefully.
Updating your Forge app
If you don't have a Forge app yet, create one using the Forge CLI.
In your Forge app's
manifest.yml, find or create a new
module, of a type that supports Forge's Custom UI (such as
jira:projectPage). In the module's
resources, point to the FDK module's
out directory, like so:
modules: + jira:projectPage: + - key: hello-world + title: Hello world + resource: hello-world-resource resources: + - key: hello-world-resource + path: ../hello-world/out
Also make sure that your
manifest.yml includes the following
permissions: + content: + styles: + - 'unsafe-inline' + scripts: + - 'unsafe-eval'
Starting your Forge app
In your Forge app's base directory, run
forge deploy forge install --upgrade
Voilà! You should now see your FDK-based Hello world app in action - in this case, using a module of type
Making your first change
To make a change to the Hello world module, open the module directory in an IDE of your choice (Visual Studio Code will work great), and navigate to the
src/index.tsx file. This file is the entry point to your module. In
src/index.tsx, you will see the React code behind Hello world. Make a small change to it - for example, change the
h3 text, like so ...
- <h3>Fine Software Forge Dev Kit</h3> + <h3>G'day!</h3>
... or write any other valid React code. Just keep exporting a React component as the file's
default export - that's expected and required by FDK.
Next, in the root directory of your module, run
yarn run generate
This will compile your code, and generate the static resources into the
Next, navigate to your Forge app's root folder, and run
When you reload Jira in your browser, you should now see your changes live.
Setting up your inner dev loop
You already deployed a change to your Forge app - well done! However, as you start making more comprehensive changes, you don't want to go through the hassle of
deploy all the time. Luckily, FDK plays well with Forge's tunneling capabilities.
First, in your module's root directory, run
yarn run dev
to start your module's
next.js development server. By default, it is running on port
Next, navigate in your Forge app's
manifest.yml, and modify your module resource definition, like so:
resources: - key: hello-world-resource path: ../hello-world/out + tunnel: + port: 3000
3000 is the port that your dev server is running on.
Next, start your app in tunneling mode, using
You can now go on to make further changes to your module, and simply reload Jira to view them live.
- Understanding your FDK module
- Recommended project structure
- Accessing your module's context
- Fetching data from Jira
- Updating data in Jira
- Navigating in Jira