@swc/plugin-emotion

@swc/plugin-emotion is a WebAssembly-based SWC plugin that provides compile-time transformations for the emotion CSS-in-JS library. It optimizes emotion-based styling code by transforming emotion API calls, adding automatic labeling, generating source maps, and performing CSS minification during the build process.

Package Information

• Package Name: @swc/plugin-emotion
• Package Type: npm (SWC Plugin)
• Language: Rust (compiled to WebAssembly)
• Installation: npm install @swc/plugin-emotion
• License: Apache-2.0

Core Imports

This plugin does not export importable functions directly. Instead, it processes existing emotion imports in your code. The plugin transforms these common emotion imports:

import { css } from "@emotion/react";
import styled from "@emotion/styled";
import { Global } from "@emotion/react";

const { css } = require("@emotion/react");
const styled = require("@emotion/styled");

Basic Usage

Configure the plugin in your SWC configuration:

{
  jsc: {
    experimental: {
      plugins: [
        ["@swc/plugin-emotion", {
          sourceMap: true,
          autoLabel: "dev-only", 
          labelFormat: "[local]"
        }]
      ]
    }
  }
}

The plugin then transforms your emotion code:

// Input
const styles = css`
  color: red;
  font-size: 16px;
`;

// Output (transformed)
const styles = css(
  "color:red;font-size:16px;",
  "label:styles;",
  "/*# sourceMappingURL=... */"
);

Architecture

@swc/plugin-emotion is built around several key components:

• Plugin Entry Point: Main SWC plugin interface that processes configuration and delegates to the transform engine
• Transform Engine: Core transformation logic that analyzes and rewrites emotion API calls
• Import Mapping System: Registry of supported emotion libraries and their export patterns
• Label Generation: Automatic CSS class name labeling with customizable formats
• Source Map Generation: Inline source map creation for debugging transformed CSS
• CSS Minification: Comment removal and whitespace optimization for CSS strings

Capabilities

Plugin Configuration

Configure the plugin behavior including source maps, automatic labeling, and label formats. Essential for integrating with your build pipeline and development workflow.

interface EmotionPluginConfig {
  sourceMap?: boolean;
  autoLabel?: "never" | "dev-only" | "always";
  labelFormat?: string;
}

Plugin Configuration

CSS Function Transformations

Transforms emotion css function calls and template literals, adding labels and source maps while minifying CSS content.

// Transforms these patterns:
// css`styles...`
// css({ styles })
// customEmotion.css`styles...`

CSS Transformations

Styled Component Transformations

Transforms emotion styled component calls, adding target class names and labels for better debugging and optimization.

// Transforms these patterns:
// styled.div`styles...`
// styled('div')`styles...`
// styled('div')({ styles })

Styled Transformations

Global JSX Transformations

Transforms emotion Global JSX components by converting styles attributes to optimized array format with source maps.

// Transforms this pattern:
// <Global styles={cssStyles} />

Global JSX Transformations

Supported Emotion Libraries

The plugin supports these official emotion libraries:

• @emotion/css: CSS function for standalone CSS-in-JS
• @emotion/styled: Styled components library
• @emotion/react: React integration with css, keyframes, and Global
• @emotion/primitives: React Native primitives
• @emotion/native: React Native styling

Error Handling

The plugin handles various error scenarios:

• Missing Configuration: Falls back to default options when plugin config is not provided
• Invalid Imports: Skips transformation for unrecognized emotion imports
• Malformed CSS: Preserves original code structure when CSS parsing fails
• Source Map Errors: Continues transformation without source maps if generation fails