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
Atlassian has standardised on Compiled CSS-in-JS as our build-time CSS-in-JS library. Compiled is an Atlassian initiative, and it is already in wide use across our products. We’re completing the transition by migrating all Atlaskit components to Compiled CSS-in-JS.
This includes the Atlassian Design System, Editor, Media, and other components — all packages in the @atlaskit npm scope currently styled using Emotion.
The primary reason we are migrating to Compiled is to improve performance — reducing the runtime performance impact and bundle size of our components, and to better leverage modern React features available in version 18 and onwards, such as concurrent rendering and streaming SSR.
Compiled’s CSS generation creates static CSS at build time, reducing JavaScript bundle size and runtime overhead. This optimisation allows for the removal of duplicate or unused styles, resulting in smaller CSS files that enhance rendering times. Additionally, static CSS files benefit from better browser caching, improving performance during repeat visits.
This move also aligns Atlassian’s coding standards and ultimately benefits both developers and customers by enabling faster product development and more reliable engineering.
We’re excited for you to benefit from this, whether you directly use Compiled in your apps, or by having faster Atlassian products upon which to build your apps for our mutual customers!
Scope of this RFC
In this RFC, we’re seeking feedback on how to best support you as Marketplace partners during this transition, including tooling and guidance.
We intend to add additional support throughout the RFC period and not just at the end, with the “Resolve” date representing the end of new additions.
- Publish: 07 Nov 2024
- Discuss: 16 Dec 2024
- Resolve: 30 Jan 2025
These changes affect apps that use Atlaskit components, built on Forge Custom UI or Connect. If you’re using Forge UI Kit, you’re good to go! No changes will be required.
Timeline for migration of packages
We have migrated a pilot component to Compiled (more detail below), and will soon be starting to migrate all Atlaskit packages.
All migrations to Compiled will be shipped as new Major versions. Our current plan:
- Oct 2024: Shipped experimental Compiled version of
@atlaskit/lozengecomponent - Nov 2024–ongoing: Provide support for Marketplace partners to adopt and troubleshoot
- Mid Nov 2024: First batch of Atlassian Design System components will be migrated to Compiled
- Late Nov–Dec 2024: Remaining Atlassian Design System components will be migrated to Compiled, along with the first Editor and Media components
- Progressively from Jan 2025: All remaining Atlaskit packages will be migrated
Asks (what this would mean for you — action may be required)
If your bundler supports CSS imports (import 'styles.css';), packages using Compiled should continue to work out of the box. We expect this to be the case in most scenarios. However, we ask all Marketplace partners to look out for possible issues, especially if you:
- Notice visual breaking changes when upgrading
- Are applying manual style overrides to
@atlaskitpackages - Use xcss via @atlaskit/primitives
- Use a bundler that is not currently configured to support CSS imports
This migration may come with unforeseen side effects, depending on the type of bundler and/or CSS-in-JS libraries used in conjunction with Atlaskit packages — there are many more combinations than we can test. We are asking for feedback on the following areas:
- Please try using our experimental Lozenge component (see next section for instructions), and report any unexpected issues or visual breaking changes.
- Do you experience any observable performance impacts (negative or positive)?
- For those of you who need to use the Compiled plugin but can’t because you’re using something other than Webpack or Parcel, please share which bundler you’re currently using below, and we will investigate/recommend a way forward.
- Are there ways this might negatively impact Marketplace partners not yet mentioned here?
We’re here to support you through this transition as best we can!
Testing compatibility using the Lozenge component
Test component entry-point: import Lozenge from '@atlaskit/lozenge/compiled';
To ensure your application is configured correctly for the migration to Compiled CSS-in-JS, we have provided a test component: @atlaskit/lozenge/compiled. This component serves as a verification tool to check if your setup supports the new CSS-in-JS solution effectively.
How to use
- Installation: Ensure that you have the latest version of the
@atlaskit/lozenge/compiledpackage installed in your project.
To check you’re on the correct version, inspectdist/cjs/compiled. You will see anindex.compiled.cssand anindex.jsimporting that file. - Integration: Integrate the test component into your application as you would with any other Atlaskit component.
+import Lozenge from '@atlaskit/lozenge/compiled';
-import Lozenge from '@atlaskit/lozenge';
- Verification: Build and run your application to verify that the component renders correctly without any styling issues. This indicates that your application is correctly configured to handle Compiled CSS-in-JS.
Troubleshooting
- If you encounter any issues, ensure that your bundler is configured to support Compiled CSS-in-JS. Refer to the specific configuration guidelines for your bundler (e.g. Webpack, Parcel) as outlined in the migration documentation.
- For Webpack users, make sure to include style-loader and css-loader in your configuration. We highly recommend using
@compiled/webpack-loaderto avoid visual regressions.
By using this test component, you can confidently proceed knowing that your application is ready to leverage the performance and consistency benefits of Compiled CSS-in-JS.
Update your bundler configuration(s)
The Compiled variants of our packages will be published to npm with internal stylesheets, such as node_modules/@atlaskit/lozenge/cjs/compiled/index.compiled.css. Your bundler must include, combine, and run the Compiled plugins over them. By default, many bundlers will load these automatically, but without @compiled/parcel-config or @compiled/webpack-loader, we cannot guarantee those styles will be ordered correctly. There is a chance of some visual regressions with this migration.
Update your bundler configuration, and if issues persist, please leave a comment below, and we will be available to assist you.
Note: Compiled does not have plugin support for every bundler, so please let us know if you require support for a specific bundler.
Using Parcel (recommended)
yarn install @atlaskit/tokens
yarn install --dev @compiled/parcel-config
Setup your .compiledcssrc:
{
"transformerBabelPlugins": [["@atlaskit/tokens/babel-plugin"]],
"extract": true,
"inlineCss": true,
"sortShorthand": true
}
Setup your .parcelrc:
{ "extends": ["@parcel/config-default", "@compiled/parcel-config"] }`
For full documentation, refer to https://atlassian.design/get-started/develop#set-up-your-bundling-environment
Using Webpack
Your configuration may vary greatly, this would be a typical production-facing Webpack config:
yarn install @atlaskit/tokens
yarn install --dev @compiled/webpack-loader mini-css-extract-plugin
const { CompiledExtractPlugin } = require('@compiled/webpack-loader');
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
module.exports = {
module: {
rules: [
{
test: /\.(js|ts|tsx)$/,
use: [
{ loader: 'babel-loader' },
{
// ↓↓ Compiled should run last ↓↓
loader: '@compiled/webpack-loader',
options: {
transformerBabelPlugins: ['@atlaskit/tokens/babel-plugin'],
extract: true,
inlineCss: true
}
}
]
},
{
test: /compiled-css\.css$/i,
use: [MiniCssExtractPlugin.loader, 'css-loader'],
},
{
test: /(?<!compiled-css)(?<!\.compiled)\.css$/,
use: ['style-loader', 'css-loader'],
}
]
},
plugins: [
new MiniCssExtractPlugin(),
new CompiledExtractPlugin({ sortShorthand: true })
],
}
For full documentation, refer to https://atlassian.design/get-started/develop#set-up-your-bundling-environment
Update your Babel configuration(s)
In order to use Compiled in Jest or CI, you must use @compiled/babel-plugin (this is preconfigured through @compiled/webpack-loader or @compiled/parcel-config).
yarn install @atlaskit/tokens
yarn install --dev @compiled/babel-plugin
// babel.config.js
module.exports = {
plugins: [
// This will handle all `token()` calls outside of Compiled
'@atlaskit/tokens/babel-plugin',
// ↓↓ Compiled should run last ↓↓
[
'@compiled/babel-plugin',
{ transformerBabelPlugins: ['@atlaskit/tokens/babel-plugin'] }
],
],
}`
For full documentation, refer to https://atlassian.design/get-started/develop#set-up-your-bundling-environment
Want to use Compiled in your app? (optional)
It’s entirely optional for partners to migrate apps to Compiled. We recommend it if you want to access the performance improvements!
If you are interested, Compiled provides automated migration tooling (codemods) to allow you to quickly migrate applications from emotion or styled-components. Please see How to migrate to Compiled? and @compiled/codemods for technical migration guidance.
-import styled from 'styled-components';
+import { styled } from '@compiled/react';
FAQs
Do I need to migrate to Compiled as well?<
No, Compiled can be used alongside other CSS-in-JS libraries. It is possible to safely interop compiled @atlaskit packages with UI components styled with other libraries (Emotion, styled-components, etc.).
However, please be aware of potential style-ordering and selector-related issues where custom overrides or hard-coded selectors may change as a result. This may happen when styling the same element with two different libraries.
What kind of breaking package changes will come with it?
While we typically expect minimal or no breaking visual changes for the majority of applications, we may be actioning some deprecations in the near future, primarily the xcss export from @atlaskit/primitives will be deprecated and replaced with the @atlaskit/css.cssMap package as described on https://atlassian.design/components/css/examples.
There may be similar breaking changes, such as props.cssFn or similar styling APIs that will not work with Compiled that may be removed, but we will try to document this in each package’s major version changelog(s). Most of them are already deprecated or linted against with our eslint tooling.
Will the existing versions of packages still work?
Yes, in the short term. You can continue to use versions prior to the Major version that migrates to Compiled, for example, until you need to test with Compiled. In the long term, we strongly recommend upgrading to benefit from improvements in UX, performance, security, and accessibility.
If you observe any side-effects let me know and we can experiment with some other approaches.
