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

[#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.

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.

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:

Fill all text fields and push the Submit button:

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:

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

App's internals

Here is the folder structure of our app:

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

[Al_Conrad]

nice one

[Taranjeet Singh]

Great information @Alexey Matveev !

[Mehmet Cengiz TURANLI]

Hi good information. but how I make hot reload reactjs

[Alexey Matveev]

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]

Thanks @Alexey Matveev 

[kmukul]

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]

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]

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ı]

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]

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]

@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]

@Mesut Can ,

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

[Mesut Can]

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

[Maciej Adamczak]

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]

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]

Good informations

[Keren Rachev]

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]

Hi @Keren Rachev

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

Thanks.

[Mahesh Gangavarapu]

@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]

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]

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_]

@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]

@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]

@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]

@Mesut Can

How did you resolve the 2nd issue?