Consuming AUI 9.x in Connect apps

We have a number of Atlassian Connect Express apps (for both JIRA and Confluence) that consume and use AUI v7.9.9 as follows:

  1. AUI packages locally installed from npm (npm install @atlassian/aui)
  2. The main layout template (layout.hbs) includes the JS/CSS bundles from /node_modules/@atlassian/aui/dist/aui/{css/aui.min.css, js/aui.min.js} in script/link tags
  3. Client-side app code relies on the presence of the window.AJS global (a side-effect of aui.min.js)

A couple of years ago (almost) when AUI 8.x was released, the packaging of AUI changed and the /dist/aui/aui.min.{js, css} bundles were replaced with /dist/aui-prototyping.{css, js}.

However at the time the 7.x -> 8.x Upgrade Guide warned:

The ‘prototyping’ bundle of AUI is not intended to be used in production systems

We briefly experimented with removing the global script tags in favour of consuming the AUI 8 components directly, e.g.

import { messages } from "@atlassian/aui";

messages.success({title: "Congratulations!", body: "It works!"});

…but for various reasons couldn’t get this working and ended up reverting back to AUI 7.9.9.

Fast forward to today, and AUI 9.x is here. So we’re just checking back in to see if there have been any improvements to consuming AUI for Atlassian Connect Express?


  1. Is including the aui-prototyping.* bundles in production systems still discouraged?
  2. Is 9.x now easier to consume directly through native imports than 8.x was, or would the same issues still exist?
  3. Are Typescript definitions (*.d.ts) available for AUI yet?

Hoping that in two years there has been some progression on this front, as we’re increasingly uncomfortable still using AUI 7.x in our apps now that there have been two major versions since.

Hi @scottohara,

There have not been any deliberate changes to improve consuming AUI via Node or for Connect. The situation is similar to how it was last time we discussed it.

Using the aui-prototyping.{js,css} files in production is discouraged due to their page weight. With that said, it may be worth testing and checking whether it has a significant impact on performance metrics in your app.

The Server Platform team are maintaining AUI for use in Server products and apps. Improving usage through Node is not planned, nor is defining types for the library. It’s not likely the team will commit to significant changes to the shape of the Node package in the next few months.

What changes to the AUI library would the most valuable to you? What are the most significant blockers? Perhaps there are changes we could discuss and plan with the Server Platform team.


Thanks for the response Daz.

Appreciate that AUI was not primarily intended for Connect apps, and understand that it isn’t currently a focus.

What changes to the AUI library would the most valuable to you? What are the most significant blockers?

I guess I’d turn that question around and ask: what guidance would Atlassian give to developers building Connect apps that:

  1. are not built in React (rules out using AtlasKit),
  2. need to show an alert or error to the user (i.e. want to align with the ADG, but don’t need the whole component library for their UI…just one or two components)

That’s the situation we find ourselves in with our apps (we only use the messages component). We also have common client-side code that we share between our Server, DC and Cloud versions, so being able to standardise on the same component library (AUI) is ideal.

Understand that with Forge just around the corner, things will change again (although it’s not quite clear to us yet what the migration process will be for moving our existing customers from Connect -> Forge; so it’s possible that we’re going to continue running our existing Connect apps until it makes sense for us to move to Forge).

If I were to list in order of priority the things we’d like to be able to achieve with AUI (or any other non-React based component library), it would be:

  1. Ability to import just the components we need
  2. Not rely on a global AJS object to exist
  3. Support for Typescript (*.d.ts definitions)

The last one isn’t critical (since we only use a few components, we can easily write our own definitions).


Thanks for the additional context @scottohara!

I must admit my ignorance at how Connect apps are built and what APIs are available. I’m asking internally and will see what advice comes back specific to this scenario re: adding a message to your page.

Re: the ability to import just the components you need + not rely on the AJS global, I’ll see what could be done. I predict some complexity to make it work across all of AUI, and build tooling would likely be a requirement.

e.g., if you import { messages } from '@atlassian/aui', would you expect that to bring in any CSS, too? We would need some way to manage the expectations around what code and how much code a given import brings in.

1 Like

Yeah, that’s a very good question.

For me personally, since we’re using Webpack to build our app (and we already use css-loader etc.), my natural inclination would be simply:

import { messages } from '@atlassian/aui';
import '@atlassian/aui/path/to/messages.css';

…but as you point out, that makes some assumptions about the build tooling being used.

I’m not normally one to jump on the “webcomponents solves everything!” bandwagon, but I do wonder if perhaps this might be a good case for publishing AUI as a set of custom elements (with styling baked into the shadow DOM).

That would obviously preclude IE (doesn’t support custom elements), but it would provide a way of consuming ADG components in a totally framework/build-agnostic manner, e.g.

<!-- import the custom element (includes all styles & behaviour) -->
<script type="module" src="node_modules/@atlassian/aui/spinner.js"></script>
<!-- use it -->
<aui-spinner size="large" filled></aui-spinner>

Anyway, appreciate that this is not a simple challenge to solve in a way that suits everybody; so I’m looking forward to hearing what advice comes back.

Thanks again for taking the time to engage on this.