@emotion/babel-plugin

11.0.0 verified Sat Apr 25 auth: no javascript

A Babel plugin for Emotion, the CSS-in-JS library, that enables automatic JSX pragma, source maps, and minification of styles. The current stable version is 11.14.0 (last updated late 2024). It is released regularly alongside the main Emotion monorepo. Unlike the older `babel-plugin-emotion` (v10), this package is scoped under `@emotion` and requires Babel 7+. Key differentiator: it is the recommended plugin for Emotion v11+, providing optimizations like label generation and dead code elimination.

Common errors

error Error: Cannot find module '@emotion/babel-plugin' ↓

cause Package not installed or wrong name used in config.

fix

Run npm install --save-dev @emotion/babel-plugin and ensure config uses the scoped name.

error Module build failed (from ./node_modules/babel-loader/lib/index.js): SyntaxError: ... Support for the experimental syntax 'classProperties' isn't currently enabled ↓

cause Missing Babel plugins for modern JavaScript syntax.

fix

Install @babel/plugin-proposal-class-properties or use the @babel/preset-env preset.

error Warning: You are using the automatic JSX runtime with Emotion's babel plugin. If you don't... ↓

cause Babel preset-react runtime mismatch.

fix

Set runtime: 'automatic' in @babel/preset-react options.

error TypeError: Cannot read properties of undefined (reading 'createElement') ↓

cause Missing import of React when using JSX without automatic runtime.

fix

Either add import React from 'react' in every file or use the automatic runtime with @babel/preset-react.

Warnings

breaking The package was renamed from `babel-plugin-emotion` to `@emotion/babel-plugin` in v11. Old imports will not work. ↓

fix Replace all references from 'babel-plugin-emotion' to '@emotion/babel-plugin'.

breaking Options API changed between v10 and v11. For example, `sourceMap` option is now under `@emotion/babel-plugin` options. ↓

fix Consult the new options documentation. Common options like `sourceMap` and `autoLabel` are still supported but need to be passed differently.

gotcha The plugin requires Babel 7+. Using with older Babel versions will fail. ↓

fix Update to Babel 7 or later. The package `@emotion/babel-plugin` does not support Babel 6.

deprecated The `labelFormat` option is deprecated in favor of `autoLabel`. ↓

fix Use `autoLabel: true` or `autoLabel: 'dev-only'` instead of `labelFormat`.

Install

npm install babel-plugin-emotion

yarn add babel-plugin-emotion

pnpm add babel-plugin-emotion

Imports

@emotion/babel-plugin
wrong
```
module.exports = { presets: ['babel-plugin-emotion'] }
```
correct
```
module.exports = { presets: ['@emotion/babel-plugin'] }
```
In v10 the package was named `babel-plugin-emotion`, in v11+ it is `@emotion/babel-plugin`. Use the scoped name.
babel-plugin-emotion
wrong
```
npm install babel-plugin-emotion@11
```
correct
```
npm install @emotion/babel-plugin@11
```
The old package `babel-plugin-emotion` only goes up to v10. The v11 version is `@emotion/babel-plugin`.
config for Babel
wrong
```
{
  "plugins": ["babel-plugin-emotion"]
}
```
correct
```
{
  "plugins": ["@emotion"]
}
```
In babel config, use the string `"@emotion"` as plugin name for v11+.

Quickstart

Shows Babel config with @emotion plugin and basic styled component using css prop.

// Install: npm install --save-dev @emotion/babel-plugin
// .babelrc
{
  "presets": [
    ["@babel/preset-react", { "runtime": "automatic" }]
  ],
  "plugins": ["@emotion"]
}

// Component
import { css } from '@emotion/react'
const style = css`
  color: hotpink;
`
function App() {
  return <div css={style}>Hello Emotion</div>
}