@emotion/babel-plugin

> Babel plugin for the minification and optimization of emotion styles.

@emotion/babel-plugin is highly recommended, but not required in version 8 and
above of Emotion.

Features

Example

In

`javascript
const myStyles = css
font-size: 20px;
@media (min-width: 420px) {
color: blue;
${css
width: 96px;
height: 96px;
};
line-height: 26px;
}
background: green;
${{ backgroundColor: 'hotpink' }};

`

Out

`javascript
const myStyles = / #__PURE__ / css(
'font-size:20px;@media(min-width:420px){color:blue;',
/ #__PURE__ / css('width:96px;height:96px;'),
';line-height:26px;}background:green;',
{ backgroundColor: 'hotpink' },
';'
)
`

Installation

`bash
yarn add --dev @emotion/babel-plugin
`

or if you prefer npm

`bash
npm install --save-dev @emotion/babel-plugin
`

Usage

$3

.babelrc

Without options:

`json
{
"plugins": ["@emotion"]
}
`

With options:

_Defaults Shown_

`js
{
"plugins": [
[
"@emotion",
{
// sourceMap is on by default but source maps are dead code eliminated in production
"sourceMap": true,
"autoLabel": "dev-only",
"labelFormat": "[local]",
"cssPropOptimization": true
}
]
]
}
`

Recommended Setup

.babelrc

`json
{
"plugins": ["@emotion"]
}
`

$3

`bash
babel --plugins @emotion/babel-plugin script.js
`

$3

`javascript
require('@babel/core').transform('code', {
plugins: ['@emotion/babel-plugin']
})
`

Options

$3

boolean, defaults to true.

This option enables the following:

- Injected source maps for use in browser dev tools

Documentation

> Note:
>
> Source maps are on by default in @emotion/babel-plugin but they will be removed in production builds

$3

'dev-only' | 'always' | 'never', defaults to dev-only.

This option enables the following:

- Automatically adds the label property to styles so that class names
generated by css or styled include the name of the variable the result is
assigned to.
- Please note that non word characters in the variable will be removed
(Eg. iconStyles$1 will become iconStyles1) because $ is not valid
CSS ClassName Selector

Each possible value for this option produces different output code:

- with dev-only we optimize the production code, so there are no labels added there, but at the same time we keep labels for development environments,
- with always we always add labels when possible,
- with never we disable this entirely and no labels are added.

#### css

In

`javascript
const brownStyles = css({ color: 'brown' })
`

Out

`javascript
const brownStyles = /#__PURE__/ css({ color: 'brown' }, 'label:brownStyles;')
`

brownStyles's value would be css-1q8eu9e-brownStyles

$3

string, defaults to "[local]".

This option only works when autoLabel is set to 'dev-only' or 'always'. It allows you to
define the format of the resulting label. The format is defined via string where
variable parts are enclosed in square brackets [].
For example labelFormat: "my-classname--[local]", where [local] will be replaced
with the name of the variable the result is assigned to.

Allowed values:

- [local] - the name of the variable the result of the css or styled expression is assigned to.
- [filename] - name of the file (without extension) where css or styled expression is located.
- [dirname] - name of the directory containing the file where css or styled expression is located.

This format only affects the label property of the expression, meaning that the css prefix and hash will
be prepended automatically.

#### css

In

`javascript
// BrownView.js
// autoLabel: 'dev-only'
// labelFormat: '[filename]--[local]'
const brownStyles = css({ color: 'brown' })
`

Out

`javascript
const brownStyles = /#__PURE__/ css(
{ color: 'brown' },
'label:BrownView--brownStyles;'
)
`

BrownView--brownStyles's value would be css-hash-BrownView--brownStyles

#### styled

In

`javascript
const H1 = styled.h1({
borderRadius: '50%',
transition: 'transform 400ms ease-in-out',
boxSizing: 'border-box',
display: 'flex',
':hover': {
transform: 'scale(1.2)'
}
})
`

Out

`javascript
const H1 = /#__PURE__/ styled('h1', {
label: 'H1'
})({
borderRadius: '50%',
transition: 'transform 400ms ease-in-out',
boxSizing: 'border-box',
display: 'flex',
':hover': {
transform: 'scale(1.2)'
}
})
`

H1's class name attribute would be css-hash-H1

$3

boolean, defaults to true.

This option assumes that you are using something to make @emotion/react's jsx function work for all jsx. If you are not doing so and you do not want such optimizations to occur, disable this option.

$3

This option allows you to tell @emotion/babel-plugin what imports it should look at to determine what it should transform so if you re-export Emotion's exports, you can still use the Babel transforms

An example file:

`js
import { anotherExport } from 'my-package'
import { someExport, thisIsTheJsxExport } from 'some-package'
`

An example config:

`json
{
"my-package": {
"anotherExport": {
"canonicalImport": ["@emotion/styled", "default"],
"styledBaseImport": ["my-package/base", "anotherExport"]
}
},
"some-package": {
"someExport": {
"canonicalImport": ["@emotion/react", "css"]
},
"thisIsTheJsxExport": {
"canonicalImport": ["@emotion/react", "jsx"]
}
}
}
`

Babel Macros

Instead of using @emotion/babel-plugin, you can use emotion with babel-plugin-macros. Add babel-plugin-macros to your babel config (which is included in Create React App 2.0) and use the imports/packages shown below.

`jsx
import {
css,
keyframes,
injectGlobal,
flush,
hydrate
} from '@emotion/css/macro'
import { jsx, css, Global, keyframes } from '@emotion/react/macro'
import styled from '@emotion/styled/macro'
``