Hello! Alexey Matveev here.

In this article, we'll be discussing how to use React and Atlaskit in Atlassian Server and Data Center apps.

Currently, if you develop an app for Atlassian Server/Data Center, your only options for building out-of-the-box UI are vm, soy, requirejs, jquery, backbone. You can read this article on the out-of-the-box features.

But this technology stack is outdated.

I personally would like to use an up-to-date technology stack that includes typescript and react in my Atlassian apps. I also like to use atlaskit library of UI elements to make my applications more portable between Server, Data Center, and Cloud.

I will make this tutorial for Atlassian Jira, but this kind of approach can be used for other Atlassian Server and Data Center products.

To follow along and practice this tutorial, you will need git and Atlassian SDK.

Let's get started!

Install Maven archetype and create a new project

I created a Maven archetype to make it simpler to create a new project with all React and Atlaskit settings and dependencies.

If you do not want to use the Maven archetype, you can clone a previously created project from this archetype. Then go to the Build and Run project part.

Clone the Maven archetype from my Bitbucket repository:

git clone https://alex1mmm@bitbucket.org/alex1mmm/jira-react-atlaskit-archetype.git --branch v1 --single-branch

Move to the jira-react-atlaskit-archetype folder, and install this archetype into your local Maven repository:

code snippet

Move to the jira-react-atlaskit-archetype folder, and install this archetype into your local Maven repository:

code snippet

After the Maven archetype is installed, move out of the archetype’s folder and create a new project based on this archetype:

code snippet

You will be asked to choose the archetype you need. I have the following local Maven archetypes:

code snippet

We need the ru.matveev.alexey.atlas.jira:jira-react-atlaskit-archetype-archetype archetype. In my case, number 3 is the correct answer.

Afterward, you will be asked to enter the groupid and artifactid for your new project. Here’s an example:

terminal output

Build and run the project

Now that my-tutorial folder was created, we need to move to the newly created folder and package this project:

Terminal commands

After the project is packaged, move it to the backend folder and run Atlassian Jira:

Terminal commands

Test application

After Atlassian Jira has been launched, copy and paste the following URL in your browser:

Test application

After Atlassian Jira has been launched, copy and paste the following URL in your browser:

Atlassian marketplace for Jira

You can see the menu of our app in the React section. But before trying our Atlaskit elements go to System -> Logging and Profiling and add the INFO logging level for the react.atlaskit.tutorial.servlet package.

Default loggers

Now go back to Manage apps and click the Form menu option. You will see a form for entering data. This form was produced by the Form Atlaskit element:

Manage apps form

Fill all text fields and push the Submit button:

Manage apps form

Now you can open the atlassian-jira.log file and find a line like this:

text to add in atlassian jira log file

It means that the data you entered in the form were caught by the backend servlet and logged into the log file.

Now let’s choose the Dynamic Table menu item in the React section. You will see the Dynamic Table Atlaskit element:

Dynamic Table Atlaskit element

That is our application. Now let’s see how it all works!

App’s internals

Here is the folder structure of our app:

Folder structure

backend contains Atlassian Jira app created from Atlassian SDK.

frontend contains UI elements which will be used in our Atlassian Jira app.

pom.xml is a parent project pom which defines two modules:

code snippet

Now let’s have a look at the frontend folder.

Frontend

The fronted folder contains files and folders which provide UI interface for our app. Here are the contents of this folder:

Frontend folder structure

Let’s describe all important files and folders:

package.json – an npm configuration file and contains:

a list of packages your project depends on
versions of packages that your project can use using semantic versioning rules. We have all dependencies for typescript, atlaskit, babel and so on.

.babel.rc – configuration file for Babel. Babel is a toolchain that is mainly used to convert ECMAScript 2015+ code into a backward-compatible version of JavaScript in current and older browsers or environments. We write all our code in Typescript and we need to convert Typescript code to JavaScript, so that our Atlassian Jira app could understand what we wanted to say.

webpack.config.js – configuration file for webpack. Webpack is a static module bundler for modern JavaScript applications. When webpack processes your application, it internally builds a dependency graph that maps every module your project needs and generates one or more bundles. We need to provide a single JavaScript file with all dependencies so that the Jira app could produce our UI elements.

Let’s have a look at the code for webpack.config.js:

code snippet

As you can see from the first line we use atlassian-webresource-webpack-plugin. Why do we need this plugin?

After the webpack created a JavaScript file for us we need to include this file into the resource section of atlassian-plugin.xml file in our Jira app. We could do it manually, but it is better to automate it. Here are the setting for this plugin:

code snippet

As the result of the settings we will have a file called wr-defs.xml created in the backend/src/resources/META-INF/plugin-descriptors folder.

With locationPrefix parameter we said that JavaScript files will be placed into backend/src/resources/frontend. We will place the JavaScript files in this folder later in backend. We use this parameter here so that we could have the following line in our bundle <resource type=”download” name=”bundled.dynamictable.js” location=”frontend/bundled.dynamictable.js”/>.

Here are the contents of the wr-defs.xml file which was generated by atlassian-webresource-webpack-plugin during packaging:

code snippet

As you can see we have resource sections for atlassian-plugin.xml where all our JavaScript files are defined. All we need to do is to add all these resource sections to our atlassian-plugin.xml file which is in the backend/resources folder. To accomplish it we modified the pom.xml in the backend folder:

code snippet

We added <Atlassian-Scan-Folders>META-INF/plugin-descriptors</Atlassian-Scan-Folders> so that during our app installation Jira would scan the META-INF/plugin-descriptors folder for additional configuration settings for atlassian-plugin.xml.

Also we added <compressResources>false</compressResources> to disable the minification of JavaScript files. All our JavaScript files are already minified.

We defined the following entry points in the webpack.config.js file:

code snippet

It means that webpack will scan ./src/form.js and ./src/dynamictable.js and create a separate JavaScript file for each file with all dependencies and put the two files in the frontend/dist folder.

./src/form.js and ./src/dynamictable.js contain nothing special. Most of the code I took from Atlaskit examples for the Form and Dynamic Table elements. Let’s examine the form.js file:

code snippet

It contains just one line to import the From class from the ./js/components/Form file. Here are the contents of ./js/components/Form

code snippet

All lines are taken from Atlaskit examples except these lines:

code snippet

I added these lines to show the MyForm in the div container after the page is loaded. We will define this div container later in the backend in a soy template.

Also pay attention to this line:

code snippet

document.getElementById(“contextPath”).value takes the value of the contextPath input element in our soy template. I pass to this element the context path of our application from the servlet from which I call this soy template. I will talk about it later.

So, that is it for fronted. As a result of packaging the frontend module we have two JavaScript files in the frontend/dist folder and xml bundle for atlassian-plugin.xml in the backend/src/resources/META-INF/plugin-descriptors.

Let’s move to the backend.

Backend

I added the following plugins to backend/pom.xml

code snippet

properties-maven-plugin creates a file called maven.properties which contains all maven properties. I need the atlassian.plugin.key property to call the web resource correctly. I will show you later how I use it.

maven-resources-plugin takes JavaScript files from frontend/dist and places these files into backend/resources/frontend.

Next I created a web section called React and two web items called Form and Dynamic Table. I created two servlets and called these servlets from the Form and Dynamic Table web item. Here are the lines from atlassian-plugin.xml:

code snippet

So we have our menu items which call our servlets. Now let’s have a look at the servlets.

FormServlet.java:

code snippet

I define two fields resourceService and soyTemplateRenderer and initialize these fields in the constructor. resourceService is my bean to read maven.properties file. soyTemplateRenderer is a Jira bean to call soy templates.

In the doGet method I get the atlassian.plugin.key property and contextPath. As I said above I need the context path to call this servlet from the Form element on the onsubmit event. Context path contains prefix of you Atlassian Jira url. In my case /jira. Then I pass contextPath as a parameter to my soy template and call servlet.ui.form soy template.

Here is the soy file:

code snippet

As you can see the templates are quite simple. All the templates do is to call required atlassian-plugin.xml web resources and define the div container where react will place all our UI elements.

This soy file was added into atlassian-plugin.xml in the web resource section:

code snippet

And that’s it! Practice this and you’ll master React and Atlaskit in your Atlassian apps.

React and Atlastkit in Atlassian server & data center apps

Subscribe for updates