RFCs are a way for Atlassian to share what we’re working on with our valued developer community.
It’s a document for building shared understanding of a topic. It expresses a technical solution, but can also communicate how it should be built or even document standards. The most important aspect of an RFC is that a written specification facilitates feedback and drives consensus. It is not a tool for approving or committing to ideas, but more so a collaborative practice to shape an idea and to find serious flaws early.
Please respect our community guidelines: keep it welcoming and safe by commenting on the idea not the people (especially the author); keep it tidy by keeping on topic; empower the community by keeping comments constructive. Thanks!
Project Summary
As many of you noticed, Atlaskit packages started supporting React 18 more than a year ago and we’ve made massive progress in that time and have a full update on plans for supporting different versions of React and the impact of this rollout on our partners and ecosystem.
Problem
While many of you are already on React 18, this may have an impact in some scenarios, and we’d like to know how we can best land this project.
We’re going through this migration for a lot of reasons, but to say the top-of-mind:
- To directly improve and unblock future opportunities to improve the performance our own products and ultimately we’re aiming to improve the experience for our customers.
- It’s what we all want—developers, ourselves and our partners, want to work with modern technology and not be held back by outdated versions.
However, this has been a lengthy migration as React 17, React 18, and React 18’s new APIs have added complexity and breaking changes that had to be solved foundationally and tested internally before any timelines were known.
It’s worth saying something given React 19 has gone stable that we’re aware that migration will be even more complex. We have no current plans with React 19, but this project has been a massive step in the right direction and we should all consider the APIs being removed in React 19 fully deprecated to make a future migration more simple.
Proposed solution
The current state of our support for React versions is as follows:
- React 16 and React 17 have been deprecated internally for some time now as most of our key products are running on React 18 with the legacy render
- More than 90% of applicable Atlaskit packages currently support React 18, as denoted via their
package.json
’speerDependencies
- We’re currently focused on supporting the new React 18
createRoot
API (modern aka concurrent rendering), as products look to utilize it
With this, our products are now able to tap into React 18’s new features which I’ll divide into two plans going forward, both which may have some impact on ecosystem apps.
We’re formally dropping support for React 16 and React 17
Today, more than 90% of the maintained packages in our public @atlaskit/*
scope support React 18. Refer to each package’s peerDependencies
entry as the source-of-truth for that support.
- If a package does not currently have support listed, they have already been asked internally and this is expected in the next few months for packages used in these products
- If a package supports it and you experience an issue, consider it a bug report like any other! There are a few known issues with concurrent rendering being resolved currently
In the coming months, we’re looking to drop intentional support for React 16 and 17 for packages in the @atlaskit/*
scope. The main technical change here is our packages will no longer be tested through automated CI in a React 16.8 environment as they are today, and instead everything will run in a React 18 concurrent environment, where possible.
For most maintained packages in this @atlaskit/*
scope, the peerDependencies
will be updated to reflect it only supports React 18 in the near future, signifying that release.
We don’t expect to make breaking changes overnight as we’ll limit the use of new APIs to be backwards-compatible as this change will have internal and ecosystem impacts. However, without CI running on these versions, we can’t guarantee changes these don’t creep in, especially through third-party dependency upgrades, so future versions may be gated by a React 18 upgrade.
Timeline:
- Currently: Atlaskit packages are still migrating to support React 18 — we’re above 90% support as of writing. A very tiny amount of packages still have bug fixes hidden behind internal feature flags meaning they don’t fully support React 18 concurrency which we’re hoping will be unblocked prior to our full releases.
- From January 2025: Expect major versions of packages to drop support via
peerDependencies
, signifying we’re no longer testing those on React 16 - By February 2025: All Atlaskit packages used in Jira and Confluence are expected to support React 18 and concurrency
- By July 2025: All Atlaskit packages that are actively maintained are expected to support React 18 and concurrency
Your apps may be rendered inside a React 18 concurrent root
As early as January 2025, the cloud versions of Confluence and Jira will start rendering content inside of the new ReactDOM.createRoot and ReactDOM.hydrateRoot concurrent APIs and possibly the ReactDOM.renderToPipeableStream API after that.
We’re currently undergoing multi-quarter effort to uplift and test these new APIs internally and while we finish that, we’re looking to see if there’s any concerns on the wider ecosystem partners.
- For Connect and Forge Custom UI Apps: while we’ve resolved an internal issue with event bubbling, no impact is expected as you maintain your own root and React version
- For Forge UI Kit Apps:
there’s a chance of breaking changes from either the React 17 event bubbling change or with React 18’s concurrent rendering where renders may be batched or even discardedEdit: at this point, no update to the Forge UI Kit reconcilier is planned, this was misunderstood. Same “no impact is expected” for Forge UI Kit Apps.
Timeline:
- Currently: Working through internal support for Atlaskit, Jira, and Confluence to support React 18 and React 18
createRoot
andhydrateRoot
, followed byrenderToPipeableStream
in the future - From January 2025: Users will start being served content rendered with the React 18
createRoot
andhydrateRoot
concurrent API in Jira and Confluence (through separate rollouts), and your ecosystem apps may be rendered into that environment
These rollouts may take months to land in full and will be thoroughly tested through internal dogfooding before customers see them and we will take care to investigate and review this RFC’s feedback and adjust where necessary.
Asks
You’ve been asking us for React 18 and even though we’ve been a bit quiet and internalized this until now, Atlassian has been very committed to landing this—for our partners, our developers, and our customers.
What we need is to know how we best support our partners with this project. Tell us if there’s anything to investigate and explore or if there’s any missed concerns we should answer and we will take this into immediate consideration and planning.
Going forward:
- Recommended action: If you haven’t already, please migrate your app to React 18 and turn on
createRoot
concurrency in your local and testing environments! Our packages should support you now, or soon.- It’s also suggested that you action the deprecations and guidance that the React team suggest (eg. in the React 19 migration guide), as they will go away in future versions and may be a problem in concurrent rendering.
- Supporting you: If you’ve encountered specific issues on the latest version of our packages that say they support React 18 or have a specific package that’s missing React 18 support, please create a new topic and we will triage them like any other bug.