Jira Front-end API

Jira DC allows you to interact with its JavaScript API and resources to facilitate building plug-ins. It also consists of guarantees we make to stabilize front-end components.

Accessing the APIs

require()

Jira DC front-end API consists of selected modules exposed via AMD and can be accessed with the global require function. It accepts an array of module names and gives a reference to the dependencies in a callback function.

1
2
require(['jira/api/jquery-2.2.4', 'jira/api/underscore-1.8'], function($, _) {
  // your resources can be accessed now
});

To be able to load a module, one must explicitly include it as a <dependency> in your <web-resource>. See the Web Resource Plugin Module documentation for details.

define()

In order to create your own module, you can specify it with define function:

1
2
define('mycompany/things/helper', ['some', 'module', 'dependencies'], function(some, module, dependencies) {
  var helper = { ... };
  return helper;
});

It is advised to prefix your module definition with your company or plugin name. The usage of prefixes jira and atlassian is forbidden.

List of APIs

Jira front-end API is exposed in jira-frontend-api plugin. To be consumed by AMD (either in require or in define list of dependencies), the dependencies need to be added to atlassian-plugin.xml:

<dependency>jira-frontend-api:jquery-2.2.4</dependency>

The documentation for the available APIs will be published soon.

Transitive dependencies

Accessing a resource or API without specifying it as a dependency in a web-resource for the plugin is not supported. Resources might be still loaded by another plugin or Jira itself, but this is not guaranteed.

Moreover, APIs must be called explicitly in the require function or as a dependency (define). Relying on transitive dependencies is not supported as well. This is especially important if a plugin consumes a private Jira API—dependencies, function signatures, and shapes might change between patch versions.

Incorrect:

1
2
define('mycompany/moduleA', ['jira/api/version'], function(jiraVersion) {
  const value = jQuery("#mycompany-feature input").val(); // illegal usage of jQuery, even if jQuery is used as a dependency for jira/api/version
});

Correct:

1
2
define('mycompany/moduleA', ['jira/api/version', 'jira/api/jquery-2.2.4'], function(jiraVersion, jQuery) {
  const value = jQuery("#mycompany-feature input").val(); // correct - jQuery specified as dependency
});

You should also specify the dependencies in your atlassian-plugin.xml file:

1
2
<dependency>jira-frontend-api:version</dependency>
<dependency>jira-frontend-api:jquery-2.2.4</dependency>

Web Resource contexts

Web Resource Manager contexts are a popular way to add front-end resources (CSS, JS) to a page. The usage of wide and already full contexts might slow down Jira significantly and affect pages that are not actively taking advantage of your plugin’s capabilities.

The usage of cross-screen contexts, usually with the atl. prefix (atl.general in particular) is discouraged. Instead, you should use specific, page-level contexts for your plugin. This mitigates the impact of your plugin on Jira's performance.

Contexts spanning multiple pages may be altered even between patch Jira releases, whereas those starting with jira. or atl.jira (specialized, page-level contexts) will be changed only in minor versions. Such changes will always be communicated with affected EAP releases. New contexts will be announced there as well. The addition or the removal of contexts may be introduced in minor versions of Jira.

Web Resource deprecation

Pay attention to the restricted and deprecated tags in web resources you load, especially those outside the official API. These keywords indicate the support status of the dependencies.

Note that in case of AUI dependencies, the deprecation status corresponds to the AUI version, not the Jira version.

However, most of the resources relate to a Jira version. For example:

1
2
<deprecated since="8.4.0" remove="9.0.0" alternative="jira.webresources:marionette-4.1">
    Use marionette 4.1 for more performant views and cleaner API
</deprecated>

For more information, see web resource documentation.

You can expect that this resource is not stable or guaranteed to appear, even in patch releases after deprecated versions. Such message will appear in development console:

1
2
[DEPRECATED] "com.atlassian.auiplugin:jquery-spin" has been deprecated since 8.0.0 and will be removed in 10.0.0. Use com.atlassian.auiplugin:aui-spinner instead. Using <aui-spinner/> through jQuery is deprecated. Create a spinner element directly. (required by "com.mycompany.plugin:feature")

DOM tree

Many plugins rely on our DOM structure to fetch data. Instead, public REST API or WRM data providers should be used whenever possible. Using the DOM tree to store or to get information is discouraged.

To support plugin vendors, Jira developers commit to announce major DOM tree structure or stylesheet changes with EAP versions.

AUI components

Atlassian supports the AUI user interface library. You might want to use it to provide a seamless UI experience with your plugin.

Please note to always refer to com.atlassian.auiplugin and the official documentation. You might notice AMD modules with names related to AUI or wrappers over these components, but it is not recommended to use these in your plugins (internal modules such as jira/ajs/...). Internal Jira APIs are unstable between patch versions.

To use AUI components, a plugin must specify AUI as its dependency.

AUI components provide you with both a web resource key and an AMD module key. For example, to use the banner, we need to mark it as a dependency:

<dependency>com.atlassian.auiplugin:aui-banner</dependency>

Then, include it using AMD if it exposes a JS API:

1
2
define('mycompany/feature', ['aui/banner'], function (banner) {
  banner({
    body: 'Your <strong>license has expired!</strong> There are two days left to <a href="#">renew your license</a>.'
  });
});

Code style recommendations

While it’s possible to access all DOM content, stylesheet rules, global JavaScript methods, and all WRM resources available through the P2 plugin system within the Jira DC plugin system, such behavior is discouraged.

Internal modules

Especially, it is not recommended to use modules starting with jira other than the ones on the API list. Method names preceded by an underscore (_) should be considered private and unstable.

Code sharing

In order to decrease page load times and improve performance in general, avoid relying on loading your own versions of popular libraries like jQuery. We recommend switching to libraries provided by the API. The following table lists the available modules:

DependencyDescription
jira-frontend-api:jquery-2.2.4jQuery version shared with other places in Jira.
jira-frontend-api:underscore-1.8underscore.js - JavaScript utility library used by Jira.

Entering into force

This contract will enter into force with first public release of Jira 9.0.0.

We would like to hear your feedback—ask your questions using the j9-frontend-api tag on the Developers Forums.

Rate this page: