or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdindex.mdmacros.mdtransformation.md
tile.json

index.mddocs/

babel-plugin-emotion

A Babel preprocessing plugin for optimizing and minifying Emotion styles in CSS-in-JS applications. This plugin provides compile-time transformations that optimize emotion CSS at build time, including minification, dead code elimination, source maps, and automatic labeling.

Important Migration Notice: As of version 11.0.0, this package has been renamed to @emotion/babel-plugin. The original babel-plugin-emotion package now serves as a migration stub that throws an error directing users to update their Babel configuration.

Package Information

  • Package Name: babel-plugin-emotion
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install --save-dev babel-plugin-emotion (deprecated) or npm install --save-dev @emotion/babel-plugin (current)
  • Migration: Replace "plugins": ["emotion"] with "plugins": ["@emotion"] in your Babel config

Core Imports

The plugin is used via Babel configuration and does not require direct imports in your code. However, the plugin itself exports the following:

// Main plugin export (for Babel)
const emotionPlugin = require('babel-plugin-emotion');

// Or with the new package name
const emotionPlugin = require('@emotion/babel-plugin');

For macro usage:

// Emotion macros (when using babel-plugin-macros)
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';

Basic Usage

Babel Configuration

.babelrc

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

With options:

{
  "plugins": [
    [
      "@emotion",
      {
        "sourceMap": true,
        "autoLabel": "dev-only", 
        "labelFormat": "[local]",
        "cssPropOptimization": true
      }
    ]
  ]
}

Before and After Transformation

Input:

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

Output:

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' },
  ';'
);

Architecture

The babel-plugin-emotion is built around several key components:

  • Plugin Factory: Main function that creates the Babel plugin with configuration options
  • Macro System: Transformer macros for different emotion packages (@emotion/react, @emotion/styled, etc.)
  • AST Visitors: Babel visitors that process ImportDeclaration, JSXAttribute, and CallExpression nodes
  • Transformation Utilities: Core functions for optimizing CSS expressions and managing imports
  • Source Map Integration: Tools for preserving debugging information through transformations

Capabilities

Plugin Configuration

Main plugin configuration options and behavior for Babel integration.

/**
 * Main Babel plugin factory function
 * @param babel - Babel instance with types
 * @param options - Plugin configuration options
 * @returns Babel plugin object with visitors
 */
function emotionBabelPlugin(babel: any, options: EmotionPluginOptions): BabelPlugin;

interface EmotionPluginOptions {
  /** Enable source map generation (default: true) */
  sourceMap?: boolean;
  /** Auto label behavior: 'dev-only' | 'always' | 'never' (default: 'dev-only') */
  autoLabel?: 'dev-only' | 'always' | 'never';
  /** Label format string (default: '[local]') */
  labelFormat?: string;
  /** Enable CSS prop optimization (default: true) */
  cssPropOptimization?: boolean;
  /** Custom import mapping for re-exported emotion APIs */
  importMap?: ImportMap;
}

interface ImportMap {
  [importSource: string]: {
    [exportName: string]: {
      canonicalImport: [string, string];
      [key: string]: any;
    };
  };
}

interface BabelPlugin {
  name: string;
  inherits: any;
  visitor: BabelVisitor;
}

Plugin Configuration

CSS Transformation

Core transformation functions for optimizing CSS expressions and styled components.

/**
 * Transform CSS call expressions for optimization
 */
function transformCssCallExpression(params: TransformCssParams): void;

/**
 * Transform CSS array expressions without css wrapper
 */
function transformCsslessArrayExpression(params: TransformParams): void;

/**
 * Transform CSS object expressions without css wrapper  
 */
function transformCsslessObjectExpression(params: TransformParams): void;

interface TransformCssParams {
  state: any;
  babel: any;
  path: any;
  sourceMap?: string;
  annotateAsPure?: boolean;
}

interface TransformParams {
  state: any;
  babel: any;
  path: any;
}

CSS Transformation

Macro System

Macro transformers for different emotion packages and their configuration.

/**
 * Collection of macro transformers for different emotion packages
 */
const macros: EmotionMacros;

interface EmotionMacros {
  /** Core macro for @emotion/react */
  core: MacroFunction;
  /** Styled macro for @emotion/native */
  nativeStyled: MacroFunction;
  /** Styled macro for @emotion/primitives */
  primitivesStyled: MacroFunction; 
  /** Styled macro for @emotion/styled */
  webStyled: MacroFunction;
  /** Macro for @emotion/css */
  vanillaEmotion: MacroFunction;
}

type MacroFunction = (params: MacroParams) => void;

interface MacroParams {
  path: any;
  references: any;
  state: any;
  babel: any;
  isEmotionCall: boolean;
  isBabelMacrosCall: boolean;
}

Macro System

Types

/** Type alias for Babel AST paths */
type BabelPath = any;

/** Type alias for Babel plugin pass state */
type EmotionBabelPluginPass = any;

interface BabelVisitor {
  ImportDeclaration(path: BabelPath, state: EmotionBabelPluginPass): void;
  Program(path: BabelPath, state: EmotionBabelPluginPass): void;
  JSXAttribute(path: BabelPath, state: EmotionBabelPluginPass): void;
  CallExpression: {
    exit(path: BabelPath, state: EmotionBabelPluginPass): void;
  };
}