Wondering what’s next for npm?Check out our public roadmap! »

    @emotion/babel-plugin

    11.3.0 • Public • Published

    @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

    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.

    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 = /* #__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

    yarn add --dev @emotion/babel-plugin

    or if you prefer npm

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

    Usage

    Via .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"]
    }

    Via CLI

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

    Via Node API

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

    Options

    sourceMap

    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

    autoLabel

    '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

    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.

    css

    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

    styled

    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"]
        }
      }
    }

    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.

    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'

    Install

    npm i @emotion/babel-plugin

    DownloadsWeekly Downloads

    452,658

    Version

    11.3.0

    License

    MIT

    Unpacked Size

    208 kB

    Total Files

    26

    Homepage

    emotion.sh

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar