atlassian-plugins-react

Atlassian plugin providing React and its various dependencies for global shared use in Atlassian DC Apps.

The version of React shipped can be checked in description field in package.json. Keep it updated when bumping React!

• The P2 plugin is provided through the platform dependencies
  • In production the front-end code uses React shipped through the web resources (described below)
• The NPM package provides React dependencies solely for unit testing

Prerequisites

• Java 21 or higher
• Node.js 20+ and npm
• Yarn v4.x
• Maven 3.9+

When used as P2 plugin

Exposed web resources

com.atlassian.plugins.react:react-amd

Single bundle containing React and its dependencies, including:

• React
• React DOM
• Client React DOM
• ...more to come

com.atlassian.plugins.react:react-core-amd

Just the React core library, without any other dependencies. The AMD module's id is: atlassian/libs/react.

com.atlassian.plugins.react:react-dom-amd

React DOM library, which loads also react-core-amd, because it's dependent on it. The AMD modules' ids are: atlassian/libs/react-dom & atlassian/libs/react-dom/client.

When used as NPM package

Projects that depend on web resources in production should use as dependency the @atlassian/atlassian-plugins-react package to have the same React dependencies for non-production environment (like running unit tests).

The version of React dependencies is kept in description field.

Purpose of patch-package in the build process

During the yarn build process, we're taking the original production React files (UMD format) from node_modules and wrapping them in a custom AMD module format using Rollup.

ReactDOM has strict dependency on React! As we're setting React AMD modules id to atlassian/libs/react, we also need to change the id ReactDOM seeks for in its module factory block.

Hence, we've created a patch file (in patches folder) and are applying this change before the build process starts. This ensures that React and ReactDOM can work together seamlessly as AMD modules in the same "namespace".

Plugin versioning

Note! The version numbers used below are just examples, explaining the versioning scheme we came up with. They're not necessarily reflect real changes and actual versions of the plugin.

The versioning scheme for this plugin is as follows:

• "Traditional" semantic versioning of the plugin itself, e.g. 1.0.0.
• The version of the React library used in the plugin is reflected as a following postfix, e.g. -18.3.1. This part is only informational. A consumer quickly knows which version of React is used in the particular version of the plugin.

Example changes to the future versions

• 1.0.0: The very first release of the 1.x "branch". Exposes React 18.3.1.
• 1.0.1: A patch release. Some small changes made to the plugin. React version stayed intact - 18.3.1.
• 1.0.2: After some time, React 18.3.77 was released. As it's a patch update, the plugin version is also only bumped on the patch level.
• 1.1.0: A new minor version of the plugin is released since it exposes minor upgrade of React to 18.7.5.
• 1.1.1: A patch release of the plugin, containing a patch React bump (and maybe some patch changes to the plugin)
• 1.2.0: This time, we've only made changes in plugin's behaviour (maybe we've added new web-resources). But React version stayed the same, so we only bumped the minor version of the plugin.
• 2.0.0: A new major version of the plugin is released, because it exposes major React version 19.0.0.

Code Quality

This repository enforces the Palantir code style using the Spotless Maven plugin. Any violations of the code style will result in a build failure.

Guidelines:

• Formatting Code: Before raising a pull request, run mvn spotless:apply to format your code.
• Configuring IntelliJ: Follow this detailed guide to integrate Spotless into your IntelliJ IDE.