@compiled/babel-plugin

Babel plugin used to bake styles into your JavaScript. See installation for setup instructions.

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

Double transform
When configuring Babel watch out for inadvertently transforming your code with Compiled twice if also using one of the bundler packages. Utilizing JavaScript configuration files can help you conditionally set plugins based on your running environment.

Options

Configure in your Babel config.

// .babelrc
{
  "plugins": [
    [
      "@compiled/babel-plugin",
      {
        "importReact": true,
        "cache": true
      }
    ]
  ]
}

If you choose to configure Compiled through Webpack or Parcel (recommended), you can pass options for @compiled/babel-plugin through those configurations. See @compiled/webpack-loader and @compiled/parcel-config for more information.

@compiled/babel-plugin supports the following options:

• addComponentName
• cache
• classHashPrefix
• classNameCompressionMap
• extensions
• flattenMultipleSelectors
• importReact
• importSources
• increaseSpecificity
• nonce
• onIncludedFiles
• optimizeCss
• parserBabelPlugins
• processXcss
• resolver
• sortAtRules

addComponentName

Add the component name as a class name to the DOM in non-production environments, if styled is used.

• Type: boolean
• Default: false

cache

Will cache the result of statically evaluated imports.

• true will cache for the duration of the node process
• 'single-pass' will cache for a single pass of a file
• false turns caching off

• Type: boolean | 'single-pass'
• Default: true

classHashPrefix

Adds a prefix to the generated hashed css rule names. The valued passed to it gets hashed in conjunction with the rest of the rule declaration.

This is useful when @compiled is being used in a micro frontend environment by multiple packages and you want to avoid specificity issues. Please note that mixing this with extraction is not supported and Parcel or Webpack will throw an error if combined.

The currently accepted regex for this value is ^[a-zA-Z\-_]+[a-zA-Z\-_0-9]*$.

• Type: string
• Default: undefined

classNameCompressionMap

Don't use this!

An internal and experimental option used to compress class names.

Note that in @compiled/webpack-loader and @compiled/parcel-config, classNameCompressionMap requires extract to be true as well.

extensions

Extensions that we should consider code. We use these to identify if a file should be parsed.

• Type: string[]
• Default: ['.js', '.jsx', '.ts', '.tsx']

flattenMultipleSelectors

Flatten multiple selectors into separate rules to better deduplicate and sort styles, eg.:

css({
  '&:hover, &:focus': {
    color: 'red',
  },
});

Is transformed into the same code as this would be:

css({
  '&:hover': { color: 'red' },
  '&:focus': { color: 'red' },
});

• Type: boolean
• Default: true

importReact

Will import React into the module if it is not found. When using @babel/preset-react with the automatic runtime this is not needed and can be set to false.

• Type: boolean
• Default: true

importSources

Additional libraries that should be parsed as though they were @compiled/react imports. @atlaskit/css is a first-class alias that is supported internally and is not necessary to include here.

Specifying this is important if you are using Compiled APIs through another package using the createStrictAPI function.

• Type: string[]
• Default: undefined

increaseSpecificity

An experimental option that increases the specificity of all generated Compiled classes. Don't use this!

nonce

Security nonce that will be applied to inline style elements if defined.

• Type: string
• Default: false

onIncludedFiles

An internal option. Callback fired at the end of the file pass when files have been included in the transformation.

• Type: (files: string[]) => void
• Default: undefined

optimizeCss

Will run additional cssnano plugins to normalize CSS during the build.

• Type: boolean
• Default: true

parserBabelPlugins

Babel parser plugins to be used when parsing the source code. Define these to enable extra babel parsers (for example, typescript). See the babel docs for more context.

Usually, you will set this option through [@compiled/parcel-config] or @compiled/webpack-loader -- see there for examples.

processXcss

An option we are only using internally. Don't use!

resolver

A custom resolver used to statically evaluate import declarations, specified as either an object or module path. If this is an object, it should contain a resolveSync function with the following type signature: (context: string, request: string) => string.

• Type: string | Resolver
• Default: undefined

sortAtRules

Unused.

Suggest changes to this page ➚