Installation

Setup is required. Install the React package with npm or your package manager of choice.

npm install @compiled/react

Then configure your bundler of choice or use Babel directly.

Installation methods

(Recommended) Parcel

Install the Parcel v2 configuration.

npm install @compiled/parcel-config --save-dev

Add the compiled preset to your Parcel config.

{
  "extends": ["@parcel/config-default", "@compiled/parcel-config"]
}

See the configuration package docs for configuration options.

Webpack

We recommend Parcel, as this will be more performant, and it aligns with the Atlassian recommended tech stack.

Install the Webpack loader.

npm install @compiled/webpack-loader --save-dev

Add the loader to your Webpack config. Make sure this is defined after other loaders so it runs first.

module.exports = {
  module: {
    rules: [
      {
        test: /\.(js|ts|tsx)$/,
        exclude: /node_modules/,
        use: [
          { loader: 'babel-loader' },
          {
            // ↓↓ defined last ↓↓
            loader: '@compiled/webpack-loader',
          },
        ],
      },
    ],
  },
};

If you're shipping an app, you'll also be interested in CSS extraction. Read the Webpack CSS extraction for a step-by-step guide.

See the loader package docs for configuration options.

Babel

Local development
When developing locally its advised to use a bundler instead of Babel directly for improved developer experience.

Install the Babel plugin.

npm install @compiled/babel-plugin --save-dev

Add the plugin to your Babel config. Make sure this is defined after other plugins so it runs first.

{
  "plugins": [
    // ↓↓ defined last ↓↓
    "@compiled/babel-plugin"
  ]
}

See the plugin package docs for configuration options.

Installing the UI Styling Standard plugin

We recommend using Compiled with the UI Styling Standard ESLint plugin. This plugin ensures that the styles you write are performant, idiomatic, and easier to maintain.

Note that using this plugin will be a requirement for frontend developers at Atlassian.

Ensuring Babel and TypeScript work with Compiled

To use the css prop, you may need to update your TypeScript and Babel configuration so that those libraries are aware of Compiled.

There are two supported options you can take to set this up: automatic JSX pragma, or the classic JSX pragma. We recommend the automatic JSX pragma if you're not sure.

Automatic JSX pragma

This requires TypeScript 4.1 or higher. In your TypeScript configuration:

// tsconfig.json

{
  "compilerOptions": {
    // ...
    "jsx": "react-jsx",
    "jsxImportSource": "@compiled/react"
  }
}

In your Babel configuration:

// babel.config.json

{
  "presets": [
    // ...
  ],
  "plugins": [
    // ...
    [
      // You can also set these options on @babel/preset-react
      // directly.
      "@babel/plugin-transform-react-jsx",
      {
        "runtime": "automatic",
        "importSource": "@compiled/react"
      }
    ]
  ]
}

If you don't want to set this globally, and instead want to set this on a per-file basis, you can use /** @jsxImportSource @compiled/react */. You can use this in conjunction with the jsx-pragma rule from our ESLint plugin to have this added for you automatically.

/** @jsxImportSource @compiled/react */
import { css } from '@compiled/react';

const someStyles = css({ /* ... */ });
const Button = <button css={someStyles}>Button text</Button>;

Classic JSX pragma

In your TypeScript configuration:

// tsconfig.json

{
  "compilerOptions": {
    // ...
    "jsx": "react",
    "jsxFactory": "jsx",
    "jsxFragmentFactory": "React.Fragment"
  }
}

In your Babel configuration:

// babel.config.json

{
  "presets": [
    // ...
  ],
  "plugins": [
    // ...
    [
      // You can also set these options on @babel/preset-react
      // directly.
      "@babel/plugin-transform-react-jsx",
      {
        "runtime": "classic",
        "pragma": "jsx",
        "pragmaFrag": "React.Fragment"
      }
    ]
  ]
}

If you don't want to set this globally, and instead want to set this on a per-file basis, you can use /** @jsx jsx */, as well as /** @jsxFrag React.Fragment */ if needed. You can use this in conjunction with the jsx-pragma rule from our ESLint plugin to have /** @jsx jsx */ added for you automatically.

/** @jsx jsx */
import { css, jsx } from '@compiled/react';

const someStyles = css({ /* ... */ });
const Button = <button css={someStyles}>Button text</Button>;

Suggest changes to this page ➚