What should i use: AUI or Atlaskit


I am starting with a new Confluence Cloud plugin. During research I found that there are 2 UI approaches: AUI and Atlaskit.

What is the right one to choose for a new plugin using atlassian-connect? What are the pros and cons for or against one of the approches?

Thanks in advance

HI @ThorstenKamann,

Ok, so it is important to understand that the underlying design principles for all product development at Atlassian is determined by the Atlassian Design Guidelines V3 (or ADG3), which can be found at https://atlassian.design

On that page, you will also find a very limited subset of React components maintained by the Atlassian Design System team (DS). Unfortunately, the cool kids of the Design System Team are either completely understaffed by Atlassian or are far to cool to care about anything apart from that limited subset.

As a result of either their coolness or lack of support from Atlassian engineering leadership, there is also an extended set of React components that can be found at https://atlaskit.atlassian.com. These components are often special purpose and created by Atlassian product teams to solve specific problems for the product. You will find banners saying that these components are either experimental or for internal use only. They are still published, you can still use them, but those warning basically means nobody at Atlassian gives a crap about them and that they are poorly maintained. Ye be warned, there will be dragons :dragon: if you use those components (even though some of them are core product components like the editor or media components).

Now the very cool kids of the Atlassian Design Team are either to cool for Server/Data Center or have been told by leadership not to care about those products because the only thing they do is bring in a shit load of :money_with_wings::money_with_wings::money_with_wings:, so another team within Atlassian is responsible for AUI, which is the framework that is used for Server/Data Center products. Surprisingly, this team is extremely active to a point that you wonder why they are not called the Design System Team. Unfortunately, they are bound to the quirks of Server/Data Center and are still using jQuery and AMD-style loading of dependencies. So not very cool, but it works. They are also slowly migrating Server/Data Center to ADG3, while still carrying the burden of the limitations imposed by outdated architectures.

Anyway, long story (and somewhat unveiled rant) short: if you’re only going to develop for Atlassian Cloud, and can either make due with a very limited subset or are willing to pull out your hairs screaming at your screen (and the void), you should go with DS components in combination with AtlasKit.

If you’re only going to develop for Server/Data Center, I would go with AUI.

If you’re developing for both… good luck to you sir!
At some point Atlassian told vendors to use AtlasKit on both Cloud and Server (because future), only to abandon most of AtlasKit and leaving vendors out in the cold after most of them followed up on that recommendation.

To be honest, at this point I consider both DS and AtlasKit as dead code :headstone:


@ThorstenKamann, In addition to what @remie has mentioned, there’s also the issue that the atlaskit components have a peer dependency on react ^16.8.0. I haven’t seen any indication on any plans to move to a more recent version of React.


We use AUI, and it sort of works. If you come from server, the transition is smoother. And you can use AUI with modern js.

1 Like

If you’re going down the path of AUI for Connect apps, just be aware of a couple of things:

  1. Have a read of this thread which details some of the challenges of consuming AUI. We have been stuck on an ancient version of AUI 7.x because we haven’t found a good way to consume just the parts of AUI that our apps use. Which then leads to…

  2. There are some new security requirements coming for Connect apps, one of which is that your app needs to use a Content Security Policy (CSP) that prevents unsafe-inline and unsafe-eval scripts. Atlassian’s own AUI 7.x falls foul of this because somewhere in it there is a string of JS being eval’ed.

Given that we only really used it for presenting error/warning banners for things like license issues, we’re in the process of ripping out AUI (and jQuery) from our apps, which should both help with bundle size and address the issues above.

I would echo @remie ‘s comments above that none of Atlassian’s design/component libraries are an obvious choice.

Good luck!

1 Like

Thanks for all the replies. And special thanks to @remie for the clear words.

After the first 3 replies I thought: ok, then AUI is the best choice. But after reading the reply by @scottohara I am not sure.
You said that both not a good choice. What is the alternative to build an UI that has the look’n’feel of Atlassian UI’s? Any recommendations?

We use the Atlassian Figma library for designing our apps based on ADG3. When implementing, we use DS components and/or AtlasKit whenever available. If it is not feasible to implement the designs with the available components from Atlassian, we create our own.

We are using the same front-end code for our Server/Data Center products, meaning that we will ship DS/AtlasKit/Custom ADG3 components to our Server/Data Center customers. In order to work around the different architectures issue we run our apps in an iframe in server with an Atlassian Connect poylfill.

1 Like

@remie Do you have some information about this polyfill? I am playing around with an express.js with atlassian-connect.js included, only.

This is for Server/Data Center only. We’re still working on making it open source, but in essence we’ve re-implemented all the methods on AP and are using window.postMessage() to communicate with the host on which we implemented an message event listener.