$ npm install @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.
Feature/Syntax | Native | Babel Plugin Required | Notes |
---|---|---|---|
css`` |
✅ | ||
css(...) |
✅ | Generally used for object styles. | |
components as selectors | ✅ | Allows an emotion component to be used as a CSS selector. | |
Minification | ✅ | Any leading/trailing space between properties in your css and styled blocks is removed. This can reduce the size of your final bundle. |
|
Dead Code Elimination | ✅ | Uglifyjs will use the injected /*#__PURE__*/ flag comments to mark your css and styled blocks as candidates for dead code elimination. |
|
Source Maps | ✅ | When enabled, navigate directly to the style declaration in your javascript file. | |
Contextual Class Names | ✅ | Generated class names include the name of the variable or component they were defined in. |
In
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
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' },
';'
)
yarn add --dev @emotion/babel-plugin
or if you prefer npm
npm install --save-dev @emotion/babel-plugin
.babelrc
(Recommended).babelrc
Without options:
{
"plugins": ["@emotion"]
}
With options:
Defaults Shown
{
"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
{
"plugins": ["@emotion"]
}
babel --plugins @emotion/babel-plugin script.js
require('@babel/core').transform('code', {
plugins: ['@emotion/babel-plugin']
})
sourceMap
boolean
, defaults to true
.
This option enables the following:
Note:
Source maps are on by default in @emotion/babel-plugin but they will be removed in production builds
autoLabel
'dev-only' | 'always' | 'never'
, , defaults to dev-only
.
This option enables the following:
label
property to styles so that class names
generated by css
or styled
include the name of the variable the result is
assigned to.iconStyles$1
will become iconStyles1
) because $
is not valid
CSS ClassName SelectorEach possible value for this option produces different output code:
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,always
we always add labels when possible,never
we disable this entirely and no labels are added.In
const brownStyles = css({ color: 'brown' })
Out
const brownStyles = /*#__PURE__*/ css({ color: 'brown' }, 'label:brownStyles;')
brownStyles
's value would be css-1q8eu9e-brownStyles
labelFormat
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.
In
// BrownView.js
// autoLabel: 'dev-only'
// labelFormat: '[filename]--[local]'
const brownStyles = css({ color: 'brown' })
Out
const brownStyles = /*#__PURE__*/ css(
{ color: 'brown' },
'label:BrownView--brownStyles;'
)
BrownView--brownStyles
's value would be css-hash-BrownView--brownStyles
In
const H1 = styled.h1({
borderRadius: '50%',
transition: 'transform 400ms ease-in-out',
boxSizing: 'border-box',
display: 'flex',
':hover': {
transform: 'scale(1.2)'
}
})
Out
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
cssPropOptimization
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.
importMap
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 config:
{
"my-package": {
"anotherExport": {
"canonicalImport": ["@emotion/styled", "default"],
"styledBaseImport": ["my-package/base", "anotherExport"]
}
},
"some-package": {
"someExport": {
"canonicalImport": ["@emotion/react", "css"]
},
"thisIsTheJsxExport": {
"canonicalImport": ["@emotion/react", "jsx"]
}
}
}
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.
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'
© 2010 - cnpmjs.org x YWFE | Home | YWFE