Jira DC Front-end API Announcement

We are happy to announce the official Jira Front-end API coming in Jira 9.

We’re looking forward to collaborating with app vendors and customers on delivering high-quality reusable components and solutions that’ll provide a better experience for Jira users.

Highlights

  • Established communication patterns: we’ll announce any changes in the scope of the contract from the Jira DC team and will inform you about deprecated or removed resources from the front-end side in advance.
  • Official recommendations for app vendors: we’re going to deliver guides on how to write secure and performant apps.
  • Officially supported APIs and libraries: in Jira 9.0.0, we deliver a small subset of libraries and APIs to facilitate the development of apps. We’re looking to expand this modest catalog a lot with your support.

Here’s the first API overview: Jira Front-end API.

If you have any comments, just post them below.

Happy testing,
The Jira team

5 Likes

Sounds great. Can you please outline how to use Atlaskit together with Jira 9 and these new APIs.
Most app vendors are using Atlaskit already for Server/DC.
thanks,
Bernhard

I’m not sure if you will be able to get Atlaskit Components this way as there are too many versions available. I think it would be quite tricky to support multiple atlaskit versions in your app

I would strongly recommend using iframe in your Server/DC app if you are planning to use AtlasKit, React, etc.

2 Likes

I am already using Atlaskit in server/dc and it already works fine (for over two years now). I am simply generating a bundle with create-react-app. The bundle with react and everything is loading on page load. My app has dedicated pages so no Jira core pages are “slowed” down by my bundle, so I am living with this tradeoff. It is fast enough since my bundle is not that large.

But I would generally prefer loading react and maybe other bigger dependencies via this new api but it would have to be a specific version.
I am not sure if Atlassian will provide react and/or Atlaskit components as dependencies and also if they will provide stable versions to rely on…

Thank you for your comments!

Providing React (and react-dom) is high on our priorities list.

We had lots of discussions on API stability.
We’re going to follow the model described in the documentation, where we’ll gradually replace React with newer version, whenever there’s internal (consuming new features, performance) or external (security, feedback from you) demand for it. Also, such changes will be announced early to make sure everyone has the time to adjust.

1 Like

To be honest I don’t think we would ever use React dependencies provided by the host product, we would then be locked in to the version of React provided by the oldest Jira version we support, I don’t think the benefits would outweigh that con for us.

I understand you aim to update the version of React you ship frequently, but plenty of vendors release a single version of their app that supports many older Jira versions, so effectively we would be locked in to the version from the oldest non-EOL Jira version that contains React as a dependency for apps to use.

1 Like

In addition to what Reece mentioned: the problem is also that if you are using AtlasKit components that have not yet been migrated to Emotion, because the Design System team conveniently decided they were not responsible for them and now it seems nobody owns them within Atlassian, you are still stuck with Styled Components 3.2.6 and thus React <17. If you’re using the React version from the host product, your app might suddenly stop working.

I hope you realise that you’re opening a can of worms with this @skorytnicki. Until Atlassian actually starts giving a damn about AtlasKit, I would not encourage vendors to use this Frontend API

2 Likes

Any new apps from us will be using Material, It’s less painful that way. We will also start to migrate the AtlasKit components to material as well

Hello everyone!

I’d like to highlight the rationale of the contract, what it means for us now, and what might be the next steps in the future.

The main reason for the contract to be published now is to prepare the ecosystem and set the expectations around the front-end layer of Jira DC in the upcoming versions. The overarching goal is performance improvements. We plan to remove a lot of legacy code and clean up dependency graphs across the codebase. It may cause changes to the order of JS execution, updates to DOM structure and eventually invalidate some hidden assumptions that apps may have embodied. While it should not cause issues for JS code that does not make those assumptions, we are aware that no code is perfect and there may be transitive dependencies that grew over time, among others.

The discussion about the Atlaskit is about the code sharing problem, which is on our radar as well, however, it is not a trivial problem and we plan to focus on removing unused code and cleaning up dependency graphs first. In the future, when we start tackling the code sharing problem, we will be proactive with the community, to create a solution that focus on the end-users and is manageable from both Jira DC team and the ecosystem perspectives.

Given our learnings that increased load times are frequently a result of increased quantity of code due to a blend of contributing factors, reducing the amount of code will heavily contribute to end-user performance.

For the near future, the most important part of the contract is about making sure that in the code of the app there are no transitive dependencies or hidden assumptions about the availability of certain modules. All of the used JS modules, variables from the run-time, should be expressed via explicit dependencies so that there’s a guarantee they will be loaded and available for the app code, which needs them.

Moreover, there’s much more you can do in the app in order to not cause performance degradation on the client side. For example, loading the app code only when it’s needed (i.e. not misapplying global contexts) or lazy loading the app features which are not crucial to the user experience on a given page (i.e. keeping critical path as lean as possible). We plan to cover these topics in the future, to leverage both modern front-end tools and Jira-specific tools like WRM 5.

Stay tuned!

3 Likes

Hey @skorytnicki - since working with a few customers of mine, I’m quite aware of the problem you are going after.
May I suggest an alternative or complementary approach?

I discovered one customer had 7 apps installed loading frontend resources in the issue view context, all of them bundled react. As a first step, it would be helpful for customers to make it easier to identify those apps, for example with a badge indicating the bundle size of the web-resources, or alternatively, make it a check in the DC approval process in order to catch these problems, before they reach the customer.

I personally found that loading react in this context is not worth it and I only load it in project page modules for my own apps

Hey folks,

Thank you for your comment, @ernst.stefan. We ran into similar problems in our support cases. Better performance of Jira is indeed a joint journey of Atlassian and vendors.

However, we don’t want to introduce such quality measures as extra steps in DC apps approval process just yet, and take a more iterative approach

Also, such issues can be mitigated on the vendor side without us being strict about what’s permitted and what is not. Hopefully, sharing Jira APIs and good development practices are going to help vendors care about the performance and identify slow code paths, huge bundles, lack of lazy-loading techniques before the app reaches the customer. We believe that right now, we don’t have to explicitly limit or restrict what’s possible within the 3rd party apps. This way we don’t hurt vendors and customers, but rather enable and encourage organic improvements without pressure on either side.

This led us to a lean proposition of both API and contract, to enable improvements on Jira side first and giving vendors time to adjust their apps if necessary. For now, we want to make sure that we won’t break apps by removing resources (think hidden transitive dependencies), changing DOM structure or bumping libraries.

Cheers!

1 Like

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.