React and Atlaskit in Atlassian Server/Data center apps Part 1

Hello!

In this article I would like to provide a solution on how to use React and Atlaskit in Atlassian Server/Data center apps.

Intro

Currently, if you develop an app for Atlassian Sever/Data center apps all you have for building UI out of the box is vm, soy, requirejs, jquery, backbone. I wrote an article on the out of the box features.

But this technology stack is outdated. I personally would like to use up to date technology stack which includes typescript and react in my Atlassian apps. Also to make my application more portable between Server/Data Center and Cloud I would like to use atlaskit library of UI elements.

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

To reproduced all steps in this tutorial you would need git and Atlassian SDK.

Let's start!

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 already created project from this archetype and 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:

cd jira-react-atlaskit-archetype
atlas-mvn install

After the Maven archetype was installed move out of the archetype's folder and create a new project based on this archetype:

cd ..
atlas-mvn archetype:generate -DarchetypeCatalog=local

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

1: local -> com.cprime.jira.sil.extension:sil-extension-archetype (This is the com.cprime.jira.sil.extension:sil-extension plugin for Atlassian JIRA.)
2: local -> ru.matveev.alexey.sil.extension:sil-extension-archetype (This is the ru.matveev.alexey.sil.extension:sil-extension plugin for Atlassian JIRA.)
3: local -> ru.matveev.alexey.atlas.jira:jira-react-atlaskit-archetype-archetype (jira-react-atlaskit-archetype-archetype)

We need the ru.matveev.alexey.atlas.jira:jira-react-atlaskit-archetype-archetype archetype. In my case it is number 3 that is why I provided number 3 as the answer.

Then you will be asked to enter the groupid and artifactid for your new project. I answered the following way:

Define value for property 'groupId': react.atlaskit.tutorial
Define value for property 'artifactId': my-tutorial
Define value for property 'version' 1.0-SNAPSHOT: : 
Define value for property 'package' react.atlaskit.tutorial: : 
Confirm properties configuration:
groupId: react.atlaskit.tutorial
artifactId: my-tutorial
version: 1.0-SNAPSHOT
package: react.atlaskit.tutorial
 Y: : Y

Build and Run project

In my case the my-tutorial folder was created. We need to move to the newly created folder and package this project:

cd my-tutorial
atlas-mvn package

After the project was packaged move to the backend folder and run Atlassian Jira:

cd backend
atlas-run

Test application

After Atlassian Jira has been started go to the following url in your browser:

http://localhost:2990/jira

You need to login with the default credentials: admin:admin and go to cog-item -> Manage apps.

Screenshot 2020-05-10 at 08.29.47.png

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.

Screenshot 2020-05-10 at 08.40.42.png

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:

Screenshot 2020-05-10 at 08.34.25.png

Fill all text fields and push the Submit button:

Screenshot 2020-05-10 at 08.44.50.png

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

2020-05-10 08:44:29,701+0300 http-nio-2990-exec-4 INFO admin 524x12509x1 15awhw2 0:0:0:0:0:0:0:1 /plugins/servlet/form [r.a.tutorial.servlet.FormServlet] Post Data: {"firstname":"Alexey","lastname":"Matveev","description":"No description","comments":"and no comments"}

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:

Screenshot 2020-05-10 at 08.48.22.png

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

App's internals

Here is the folder structure of our app:

Screenshot 2020-05-10 at 09.13.36.png

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:

    <modules>  
        <module>frontend</module>
        <module>backend</module>
    </modules>

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

Part 2

30 comments

Al_Conrad May 10, 2020

nice one

Taranjeet Singh
Community Leader
Community Leader
Community Leaders are connectors, ambassadors, and mentors. On the online community, they serve as thought leaders, product experts, and moderators.
May 22, 2020

Great information @Alexey Matveev !

Mehmet Cengiz TURANLI July 5, 2020

Hi good information. but how I make hot reload reactjs

Alexey Matveev
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
July 6, 2020

Hello @Mehmet Cengiz TURANLI ,

pull version 2 from the repo:

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

 There is the hot reload.

Mehmet Cengiz TURANLI July 8, 2020

Thanks @Alexey Matveev 

kmukul August 12, 2020

Thanks for the wonderfully detailed article. I am not an atlassian or java developer but I am still able to follow most of the instructions. I tried both v1 and v2 branch however I see the following error. I would appreciate your guidance.

 

Unsupported platform for fsevents@2.1.3: wanted {"os":"darwin","arch":"any"} (current: {"os":"linux","arch":"x64"})

Mehmet Cengiz TURANLI August 12, 2020

Hello @kmukul 

your system is not a mac os system. follow the link for your problem solution

 https://stackoverflow.com/questions/40671567/npm-install-fsevents-errors

kmukul August 13, 2020

Thank you for quick response, I am not using mac, I was able to get past the fsevents error by making fsevents optional via following command hope that is okay?

npm i fsevents@latest -f --save-optional

I ran into another issue after that, altas run fails to start and i think the following two lines might be relevant from logs

There is insufficient memory

Starting container [org.codehaus.cargo.container.tomcat.Tomcat8xInstalledLocalContainer@149162a4] failed,

Oğulcan Tatlı August 25, 2020

I am trying to create confluence plugin with react and soy templates but soy templates are not working. do you know how to use it with confluence? I have tried:

import com.atlassian.soy.renderer.SoyTemplateRenderer;

But it gives "component import" errors.

Do you have example for Confluence?

Maciej Adamczak
Atlassian Team
Atlassian Team members are employees working across the company in a wide variety of roles.
August 25, 2020

Hi @Oğulcan Tatlı if you are having problems with `SoyTemplateRenderer` you should try checking:

1. If the maven dependency is configured in the plugin `pom.xml` file e.g

<project ...>
<dependencies>
<
dependency>
<groupId>com.atlassian.soy</groupId>
<artifactId>soy-template-renderer-api</artifactId>
<scope>provided</scope>
</dependency>
</dependencies>
</project>

2. Create the Components import class in your plugin project to load the needed services:

package com.example.plugin.osgi;

import com.atlassian.plugin.spring.scanner.annotation.imports.ComponentImport;
import com.atlassian.soy.renderer.SoyTemplateRenderer;

/**
* This class is never instantiated, it serves only to cause the necessary OSGi services to be imported as Spring proxy beans.
*/
@SuppressWarnings("unused")
final class ComponentImports {

// Needed by Servlet
@ComponentImport
private final SoyTemplateRenderer soyTemplateRenderer;

private ComponentImports() {
throw new UnsupportedOperationException("Not for instantiation");
}
}

 I hope that helps.

 

Thanks,

Maciej Adamczak
Bitbucket Developer

Mesut Can September 5, 2020

@Alexey Matveev @Maciej Adamczak 

I am working on windows machine to develop a plugin. I ran into a several problems to solve;

1. In atlas-mvn package step, I got error for fsevents mismatch my os type, should I remove it? I made it optionalDependency and proceed! (RESOLVED)

2. atlas-mvn package is never ending!(RESOLVED)

3.When I click to the form on the left side, shows blank page, and I couldnt find out what is the problem? Can you please help me about that?

Thanks in advance.

1- (it is correct way to solve for windows users!)

2-(watch is preventing it to end, anyone facing this issue should split webpack configuration by dev and prod!)

Alexey Matveev
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
September 6, 2020

@Mesut Can ,

I can not help you with it. I do not have a windows PC. Sorry.

Mesut Can September 6, 2020

@Alexey Matveev thanks I solved the problems related to windows.

Maciej Adamczak
Atlassian Team
Atlassian Team members are employees working across the company in a wide variety of roles.
September 6, 2020

Hi @Mesut Can I don't know your exact webpack config but can you double-check if the webpack-wrm-plugin is producing and generating the XML and JS files into the `target` directory?

 

You can take a look at the example project configuration here: https://bitbucket.org/atlassianlabs/bitbucket-client-side-extensions-template/src/master/config/

uidev February 12, 2021

why are all the atlaskit UI dependencies under "devdependencies" in your package.json. And why do you use *.js extension for your typescript files?

M Amine
Community Leader
Community Leader
Community Leaders are connectors, ambassadors, and mentors. On the online community, they serve as thought leaders, product experts, and moderators.
June 4, 2021

Good informations

Keren Rachev July 18, 2022

Hi, thank you a lot for this information!


I was able to run your code and everything works as expected on my local Jira instance (localhost when I run atlas-run).
But when I try uploading the .jar or .obr file to my real Jira instance as an addon, when I click on one of the options (form/dynamic tables) nothing being rendered. I just get an empty Jira page :( As if this .jar file doesn't contain the frontend code. Can you please advice on how can I fix this?

Thank you!

IbrahimTakak September 19, 2022

Hi @Keren Rachev

Did you fix this problem, I have same problem too.

 

Thanks.

Mahesh Gangavarapu October 28, 2022

@Alexey Matveev _Appfire_, thanks for the detailed information. I was able to run your code and everything works as expected on my local Jira instance (localhost when I run atlas-run).
But when I try uploading the .jar or .obr file to my real Jira instance as an addon, when I click on one of the options (form/dynamic tables) nothing being rendered. I just get an empty Jira page.

Let me know what is the fix here?

Thanks,

Mahesh

Maciej Adamczak
Atlassian Team
Atlassian Team members are employees working across the company in a wide variety of roles.
November 3, 2022

Hi @Mahesh Gangavarapu you can try using the @atlassian/wrm-troubleshooting NPM package. It should help you with troubleshooting the configuration of webpack and Atlassian P2 project.

Thanks,

Maciej Adamczak
Atlassian Developer

Vikash Kumar November 11, 2022

Can I run the frontend as an UI app independently? Without running Jira application at all.

As per readme, I am running node start then I am seeing this error:

Error: Cannot find module '/Users/vikash/dev/atlassian/jira-react-atlaskit/frontend/start'
Ajay _view26_
Community Leader
Community Leader
Community Leaders are connectors, ambassadors, and mentors. On the online community, they serve as thought leaders, product experts, and moderators.
December 8, 2022

@Alexey Matveev  Thanks for sharing this wonderful article ... Its of real help for the developer community .

Few issues which I faced with Windows 11 

In atlas-mvn package step, I got error for fsevents mismatch my os type.I made it optionalDependency and got it working

- The other issue was to do with my node version & build tools for Visual Studio 2022 on Windows 11

https://stackoverflow.com/questions/70082657/npm-err-gyp-err-when-installing-node-sass-in-windows-11-with-visual-studio-202

Solution was to downgrade my node version from 18 to 14 & Visual Studio from 2022 to 2017

Hope it helps for developers facing issue with windows!

Cheers

Ajay

Aldin Delic February 2, 2023

@Alexey Matveev Thank you for sharing this.

I was experiencing a problem with my Web-Resources since Confluence 8, because all of them were suddenly wrapped in try catch clauses. This can be resolved trough webpack and plugin.

Cheers

Aldin

Francesco R
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
October 31, 2023

@Keren Rachev and @Mahesh Gangavarapu I had the same problem. I'm newbie with webkit but I solved modifying the resource locations in the genarated backend/src/main/resources/META-INF/plugin-descriptors/wr-defs.xml from "frontend//bundled.form.js" to "frontend/bundled.form.js" and from "frontend//bundled.dynamictable.js" to "frontend/bundled.dynamictable.js"
I'm workning on Window but I'm using the git bash to work (I know, I know ... but in my corporate only Windows is allowed).
I don't know if this is the problem but this made me appear the Form and the Table after I reloaded the plugin in my localhost Jira instance running

Vishal Petkar November 20, 2023

@Mesut Can

How did you resolve the 2nd issue?

Comment

Log in or Sign up to comment
TAGS
AUG Leaders

Atlassian Community Events