0
# Plugin Configuration
1

2
Configuration options for controlling @swc/plugin-emotion behavior including source maps, automatic labeling, and label formatting.
3

4
## Capabilities
5

6
### Plugin Configuration Interface
7

8
The main configuration interface for the emotion plugin.
9

10
```typescript { .api }
11
/**
12
 * Configuration options for @swc/plugin-emotion
13
 * All options are optional and have sensible defaults
14
 */
15
interface EmotionPluginConfig {
16
  /** Enable/disable source map generation (default: true in development, false in production) */
17
  sourceMap?: boolean;
18
  /** Control when automatic labels are added to CSS */
19
  autoLabel?: "never" | "dev-only" | "always";
20
  /** Format string for generated labels with placeholder support */
21
  labelFormat?: string;
22
}
23
```
24

25
### Source Map Configuration
26

27
Controls whether inline source maps are generated for transformed CSS.
28

29
```typescript { .api }
30
/**
31
 * Source map generation setting
32
 * @default true in development environment, false in production
33
 */
34
sourceMap?: boolean;
35
```
36

37
**Usage Examples:**
38

39
```javascript
40
// Enable source maps in all environments
41
{
42
  jsc: {
43
    experimental: {
44
      plugins: [["@swc/plugin-emotion", { sourceMap: true }]]
45
    }
46
  }
47
}
48

49
// Disable source maps completely
50
{
51
  jsc: {
52
    experimental: {
53
      plugins: [["@swc/plugin-emotion", { sourceMap: false }]]
54
    }
55
  }
56
}
57
```
58

59
### Auto Label Configuration
60

61
Controls when automatic CSS class name labels are added to emotion styles.
62

63
```typescript { .api }
64
/**
65
 * Automatic label generation setting
66
 * @default "dev-only"
67
 */
68
autoLabel?: "never" | "dev-only" | "always";
69
```
70

71
**Label Modes:**
72

73
- **"never"**: Never add automatic labels
74
- **"dev-only"**: Add labels only in development environment (default)
75
- **"always"**: Add labels in all environments
76

77
**Usage Examples:**
78

79
```javascript
80
// Always add labels
81
{
82
  jsc: {
83
    experimental: {
84
      plugins: [["@swc/plugin-emotion", { autoLabel: "always" }]]
85
    }
86
  }
87
}
88

89
// Never add labels
90
{
91
  jsc: {
92
    experimental: {
93
      plugins: [["@swc/plugin-emotion", { autoLabel: "never" }]]
94
    }
95
  }
96
}
97
```
98

99
### Label Format Configuration
100

101
Customizes the format of automatically generated CSS labels using placeholder tokens.
102

103
```typescript { .api }
104
/**
105
 * Label format template with placeholder support
106
 * @default "[local]"
107
 */
108
labelFormat?: string;
109
```
110

111
**Supported Placeholders:**
112

113
- **[local]**: Variable name or context identifier
114
- **[filename]**: Current file name (without extension)
115
- **[dirname]**: Parent directory name
116

117
**Usage Examples:**
118

119
```javascript
120
// Custom label format with filename
121
{
122
  jsc: {
123
    experimental: {
124
      plugins: [["@swc/plugin-emotion", { 
125
        labelFormat: "[filename]--[local]" 
126
      }]]
127
    }
128
  }
129
}
130

131
// Include directory context
132
{
133
  jsc: {
134
    experimental: {
135
      plugins: [["@swc/plugin-emotion", { 
136
        labelFormat: "[dirname]-[local]" 
137
      }]]
138
    }
139
  }
140
}
141
```
142

143
**Label Generation Examples:**
144

145
```typescript
146
// With labelFormat: "[filename]--[local]"
147
const buttonStyles = css`color: blue;`;
148
// Generates: label: "MyComponent--buttonStyles"
149

150
// With labelFormat: "[local]"  
151
const headerStyles = css`font-size: 24px;`;
152
// Generates: label: "headerStyles"
153
```
154

155
### Complete Configuration Example
156

157
Full configuration with all available options:
158

159
```javascript { .api }
160
{
161
  jsc: {
162
    parser: {
163
      syntax: "typescript",
164
      tsx: true
165
    },
166
    experimental: {
167
      plugins: [
168
        ["@swc/plugin-emotion", {
169
          sourceMap: true,
170
          autoLabel: "dev-only",
171
          labelFormat: "[filename]--[local]"
172
        }]
173
      ]
174
    }
175
  }
176
}
177
```
178

179
### Environment-Based Configuration
180

181
The plugin automatically adapts behavior based on the build environment:
182

183
```typescript { .api }
184
/**
185
 * Environment detection affects default behavior:
186
 * - Development: sourceMap defaults to true, autoLabel defaults to active
187
 * - Production: sourceMap defaults to false, autoLabel follows setting
188
 */
189
```
190

191
**Environment Examples:**
192

193
```javascript
194
// Development environment behavior
195
process.env.NODE_ENV = "development";
196
// sourceMap: true (default), autoLabel: active if "dev-only" or "always"
197

198
// Production environment behavior  
199
process.env.NODE_ENV = "production";
200
// sourceMap: false (default), autoLabel: active only if "always"
201
```
202

203
## Advanced Configuration
204

205
### Import Map Configuration
206

207
For custom emotion library configurations, the plugin supports import mapping:
208

209
```typescript { .api }
210
/**
211
 * Import map for custom emotion libraries (advanced usage)
212
 * Maps import sources to canonical emotion transformations
213
 */
214
interface ImportMap {
215
  [importSource: string]: {
216
    [localExportName: string]: {
217
      canonicalImport: [string, string]; // [packageName, exportName]
218
      styledBaseImport?: [string, string];
219
    };
220
  };
221
}
222
```