0
# @swc/plugin-emotion
1
2
@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.
3
4
## Package Information
5
6
- **Package Name**: @swc/plugin-emotion
7
- **Package Type**: npm (SWC Plugin)
8
- **Language**: Rust (compiled to WebAssembly)
9
- **Installation**: `npm install @swc/plugin-emotion`
10
- **License**: Apache-2.0
11
12
## Core Imports
13
14
This plugin does not export importable functions directly. Instead, it processes existing emotion imports in your code. The plugin transforms these common emotion imports:
15
16
```typescript
17
import { css } from "@emotion/react";
18
import styled from "@emotion/styled";
19
import { Global } from "@emotion/react";
20
```
21
22
```javascript
23
const { css } = require("@emotion/react");
24
const styled = require("@emotion/styled");
25
```
26
27
## Basic Usage
28
29
Configure the plugin in your SWC configuration:
30
31
```javascript
32
{
33
jsc: {
34
experimental: {
35
plugins: [
36
["@swc/plugin-emotion", {
37
sourceMap: true,
38
autoLabel: "dev-only",
39
labelFormat: "[local]"
40
}]
41
]
42
}
43
}
44
}
45
```
46
47
The plugin then transforms your emotion code:
48
49
```typescript
50
// Input
51
const styles = css`
52
color: red;
53
font-size: 16px;
54
`;
55
56
// Output (transformed)
57
const styles = css(
58
"color:red;font-size:16px;",
59
"label:styles;",
60
"/*# sourceMappingURL=... */"
61
);
62
```
63
64
## Architecture
65
66
@swc/plugin-emotion is built around several key components:
67
68
- **Plugin Entry Point**: Main SWC plugin interface that processes configuration and delegates to the transform engine
69
- **Transform Engine**: Core transformation logic that analyzes and rewrites emotion API calls
70
- **Import Mapping System**: Registry of supported emotion libraries and their export patterns
71
- **Label Generation**: Automatic CSS class name labeling with customizable formats
72
- **Source Map Generation**: Inline source map creation for debugging transformed CSS
73
- **CSS Minification**: Comment removal and whitespace optimization for CSS strings
74
75
## Capabilities
76
77
### Plugin Configuration
78
79
Configure the plugin behavior including source maps, automatic labeling, and label formats. Essential for integrating with your build pipeline and development workflow.
80
81
```typescript { .api }
82
interface EmotionPluginConfig {
83
sourceMap?: boolean;
84
autoLabel?: "never" | "dev-only" | "always";
85
labelFormat?: string;
86
}
87
```
88
89
[Plugin Configuration](./configuration.md)
90
91
### CSS Function Transformations
92
93
Transforms emotion `css` function calls and template literals, adding labels and source maps while minifying CSS content.
94
95
```typescript { .api }
96
// Transforms these patterns:
97
// css`styles...`
98
// css({ styles })
99
// customEmotion.css`styles...`
100
```
101
102
[CSS Transformations](./css-transformations.md)
103
104
### Styled Component Transformations
105
106
Transforms emotion styled component calls, adding target class names and labels for better debugging and optimization.
107
108
```typescript { .api }
109
// Transforms these patterns:
110
// styled.div`styles...`
111
// styled('div')`styles...`
112
// styled('div')({ styles })
113
```
114
115
[Styled Transformations](./styled-transformations.md)
116
117
### Global JSX Transformations
118
119
Transforms emotion Global JSX components by converting styles attributes to optimized array format with source maps.
120
121
```typescript { .api }
122
// Transforms this pattern:
123
// <Global styles={cssStyles} />
124
```
125
126
[Global JSX Transformations](./global-jsx-transformations.md)
127
128
## Supported Emotion Libraries
129
130
The plugin supports these official emotion libraries:
131
132
- **@emotion/css**: CSS function for standalone CSS-in-JS
133
- **@emotion/styled**: Styled components library
134
- **@emotion/react**: React integration with css, keyframes, and Global
135
- **@emotion/primitives**: React Native primitives
136
- **@emotion/native**: React Native styling
137
138
## Error Handling
139
140
The plugin handles various error scenarios:
141
142
- **Missing Configuration**: Falls back to default options when plugin config is not provided
143
- **Invalid Imports**: Skips transformation for unrecognized emotion imports
144
- **Malformed CSS**: Preserves original code structure when CSS parsing fails
145
- **Source Map Errors**: Continues transformation without source maps if generation fails