Kickstart your next app: Tips for developing on Forge

Building a world-class ecosystem takes world-class tools. When we launched Forge, we started down a path to give developers the platform they need to learn, build, launch, and grow.

Since we announced general availability of Forge, some developers have started taking their first steps towards developing Forge apps for Jira and Confluence. In fact, this year’s Codegeist competition included more than 150 submissions of Forge apps, with several developers using the platform for the first time.  

If you’re new to building Atlassian apps and don’t know where to start, here are a few tips for success right out of the gate:

1. Review resources provided by Atlassian
2. Understand which UI to use
3. Use the Storage API to manage information
4. Connect with others who are new to building apps

1. Review resources provided by Atlassian

On our developer site, developer.atlassian.com, you’ll find guides, tutorials, example apps and documentation you can use to get on your feet quickly with Forge:

• Getting started guide – To get started using Forge, you’ll install the command-line interface (CLI), log in with an Atlassian API token, and create an Atlassian developer site that has Confluence and all of the Jira applications installed.
• Tutorials on Hello World apps for Jira and Confluence – Now you’re ready to create simple Forge apps to display content on a Jira issue or on a Confluence page. The tutorials walk you through working with apps through the CLI, making calls to the Jira and Confluence REST APIs and using UI kit components (see below).
• General tutorials – These tutorials cover topics ranging from automating Jira with triggers to using the app Storage API in a Confluence macro.
• Example apps – We’ve published more than a dozen apps to help get your wheels turning on what you can build with Forge, from a currency exchange app to a QA demo validator.

Atlassian developer YouTube channel – Find everything from roadmap webinars to talks given by Atlassian leadership to tutorials for developers all in one, centralized place.

2. Understand which UI to use

Once you understand the basics of developing on Forge, you’ll want to understand the difference between our two user interfaces: custom UI and UI kit. As their names imply, they vary in the complexity of the interactions they enable and in the visual features they’re designed for. Both custom UI and UI kit apps inherit modern security features to ensure high trust between Atlassian, developers and users.

First, you should decide if your use case is better served by UI kit (the easy, simple option). If not, then you’ll want to graduate to custom UI.

UI Kit

UI kit is designed for writing interfaces around built-in Atlassian components like hooks and event handlers. Its components adhere to the Atlassian design system and match the style of Atlassian products. UI kit is ideal for adding configuration to a Confluence macro, for example, or for displaying a small amount of data in a table inside a Jira custom glance.

UI kit is both easy to use and easy to set up. The file that generates the UI is a Forge function, which exports a render function. It lives in the same package as your other Forge functions and uses the same config files. It’s simpler than the static resource package for custom UI, and popular among developers who are navigating building a Forge app for the first time, like Jimmy Seddon at Arctic Wolf:

UI kit functions are executed in Forge’s Functions as a Service (FaaS) environment. As Marketplace Partner Tobitheo points out, their output is a single tree of HTML elements for the user’s web interface. For simplicity, they’re not designed to accommodate your own custom HTML; if you want to add any of your own, you can try the UI kit components.

In general, UI kit favors simplicity over interactivity:

• Functions executed in the FaaS environment are subject to a runtime limitation of 25 seconds.
• The only way to update your UI is to have the user click a button or submit a form, which calls your function again.
• UI kit does not include setInterval calls that can occasionally update your app.

If you need more interactivity or a more complex interface, consider custom UI.

Custom UI

Custom UI is designed for complex use cases and flexibility. Use it to define your own user interface with static resources such as HTML, CSS, JavaScript, and images. Upon deployment, the static resources are all bundled up and sent to Forge, which hosts them.

Tobitheo explains that you have latitude in how you get to that bundle. Typically, there will be a package.json you can use somewhere inside or next to the Forge package’s package.json. You can also set up webpack or parcel, or just write your own JavaScript to bundle the static resources.

You can call your own backend hosted on Forge using the custom UI bridge. The bridge allows a custom UI iframe to communicate with a Forge FaaS function, which can then make calls to allow-listed external services, like your own backend or third-party APIs. Plus, Forge functions have access to credentials injected via environment variables, so your function can authenticate with those third-party APIs.

If you have multiple modules using custom UI, you’ll have a routing decision to make:

• Declare multiple resources for the different modules and get your bundler to output all resources once per entrypoint.
• Set multiple, completely independent resource directories with separate package.json, bundler configs, etc.
• Declare one resource and do moduleKey-based routing. You can code-split for this, but it will increase your load times.

3. Use the Storage API to manage information

The Storage API provides methods to store values in the Forge app storage. Many Codegeist hackathon participants found the Storage API to be a huge benefit when building their app — don’t take our word for it, hear it directly from one of our developers who participated in Codegeist last year:

Data stored using the app Storage API is not shared between Forge apps on the same site or across different Atlassian sites. Your app alone can read and write your stored data, and the only data your app can access is the data in its environment. In fact, if your app stores data for, say, Jira, that data will not be accessible from Confluence, and vice versa.

Although the app Storage API is not designed for storing files, it’s an alternative to using product properties through the Properties API. As developer Harry Banda demonstrates, it’s versatile enough for rudimentary Create Read Update Delete (CRUD) apps, and in combination with UI kit, you can develop and maintain simple data stores.

4. Connect with others who are new to building apps

In the Forge Developer Community you’ll find hundreds of Marketplace partners, developers, and Atlassian staff members willing to share their experience and answer your questions. For new Forge developers, it can be helpful to use the community in a few ways for support:

1. The community site has thousands of questions that have already been answered. Search and browse topics in the Forge category to see if your question has been asked and answered already.
2. If not, you can ask your own question which may be answered by staff, product support, or the larger community. 

Participating in our community comes with plenty of benefits besides getting the information you need. Collaborating with other developers can spark new ideas, and getting to know our Solution Partners can give you valuable insight into the Atlassian Marketplace. 

We also host quarterly webinars presented by our product team on the state of Forge, which include recent releases and important announcements about the product roadmap. If you can’t attend in person, you can always watch the recording or read a recap on our blog.

Now it’s your turn

We hope you can use these tips and tricks to start building your next (or first) Forge app. If you get stuck along the way or have a specific question throughout your journey, be sure to ask your fellow community members to lend a helping hand.