What is babel-plugin-emotion?
The babel-plugin-emotion npm package is designed to enhance the development experience when using Emotion, a popular CSS-in-JS library. It provides optimizations and custom transformations for styles defined in JavaScript, enabling more efficient and powerful styling solutions in React applications. This plugin facilitates the use of Emotion by offering features such as source maps for easier debugging, auto-labeling for better readability of class names, and the optimization of styles for production.
What are babel-plugin-emotion's main functionalities?
Source Maps
Generates source maps for styles, improving the debugging process by allowing developers to trace back to the original location of a style definition within their code.
"use strict";
var _emotion = require("@emotion/core");
function App() {
return /*#__PURE__*/_emotion.jsx("div", {
css: {
color: 'hotpink'
}
}, "Hello World");
}
Auto-labeling
Automatically adds labels to the generated class names based on the name of the variable or component. This enhances readability in the DOM and helps in identifying components during debugging.
"use strict";
var _emotion = require("@emotion/core");
var _styled = /*#__PURE__*/(0, _emotion.default)("div")
/*#__PURE__*/
.emotionLabel('MyComponent_styled_h1nx9f');
Optimization for Production
In production, the plugin optimizes the styles by compacting and efficient handling, reducing the size of the generated CSS and improving load times.
process.env.NODE_ENV === 'production' ? /*#__PURE__*/require('@emotion/css').css('label:MyComponent;', 'color:hotpink;') : /*#__PURE__*/require('@emotion/css').css('color:hotpink;');
Other packages similar to babel-plugin-emotion
styled-components
Styled-components is another CSS-in-JS library that allows for styling applications using tagged template literals. While it offers similar functionality in terms of defining styles within JavaScript, it differs in syntax and the way styles are applied. Styled-components focuses on creating styled components without the need for a separate CSS file, whereas babel-plugin-emotion enhances the Emotion library's capabilities with additional compile-time optimizations and features.
babel-plugin-styled-components
This plugin is specifically designed for styled-components, offering similar compile-time enhancements as babel-plugin-emotion but for styled-components. It includes features like server-side rendering optimizations, better debugging with readable class names, and minification of styles for production. The comparison lies in the focus of each plugin on its respective CSS-in-JS library, providing tailored optimizations and developer experience improvements.
babel-plugin-emotion
Babel plugin for the minification and optimization of emotion styles.
The Babel Plugin is highly recommended, but not required in version 8 and above.
Feature table
Feature/Syntax | Native | Babel Plugin Required | Notes |
---|
css`` | ✅ | | |
css(...) | ✅ | | Generally used for object styles. |
styled('div')`` syntax | ✅ | | Both string and object styles work without this plugin. |
styled.div`` syntax | | ✅ | Supporting the shortcut syntax without the Babel plugin requires a large list of valid elements to be included in the bundle. |
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. |
Static Extraction | | ✅ | Generated CSS that is eligible for extraction can be moved to an external css file. |
Source Maps | | ✅ | When enabled, navigate directly to the style declaration in your javascript file. |
css as Prop | | ✅ | Convenient helper for calling css and appending the generated className during compile time. |
Example
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 = css(
'font-size:20px;@media(min-width:420px){color:blue;',
css('width:96px;height:96px;'),
';line-height:26px;}background:green;',
{ backgroundColor: 'hotpink' },
';'
)
Installation
npm install --save-dev babel-plugin-emotion
Usage
Via .babelrc
(Recommended)
.babelrc
Without options:
{
"plugins": ["emotion"]
}
With options:
Defaults Shown
{
"plugins": [
["emotion", {
"hoist": false,
"sourceMap": false,
"extractStatic": false,
"importedNames": {
"styled": "styled",
"css": "css",
"keyframes": "keyframes",
"injectGlobal": "injectGlobal",
"fontFace": "fontFace",
"merge": "merge"
}
}]
]
}
Recommended Setup
Use Babel's env
property
.babelrc
{
"env": {
"production": {
"plugins": [["emotion", { "sourceMap": false, "hoist": true }]]
},
"development": {
"plugins": [["emotion", { "sourceMap": true, "hoist": false }]]
}
}
}
Via CLI
babel --plugins babel-plugin-emotion script.js
Via Node API
require("@babel/core").transform("code", {
plugins: ["babel-plugin-emotion"]
});
Options
hoist
boolean
, defaults to false
.
This option enables the following:
- Any argument supplied to
css
or styled
is hoisted.
By hoisting the argument, or assigning the value to a variable,
emotion is able to leverage the use of a WeakMap
cache to increase performance. Users of object styles will benefit the most from enabling this option.
In
css({ color: 'brown' });
Out
var _ref = { color: 'brown' };
css(_ref);
sourceMap
boolean
, defaults to false
.
This option enables the following:
- Injected source maps for use in browser dev tools
Documentation
boolean
, defaults to
This option enables the following:
- Extract static styles into CSS files.
Documentation
importedNames
object
, defaults to
{
"styled": "styled",
"css": "css",
"keyframes": "keyframes",
"injectGlobal": "injectGlobal",
"fontFace": "fontFace",
"merge": "merge"
}
This option enables the following:
- Configurable import names
Documentation