0
# SWC Plugin for styled-components
1

2
SWC plugin that provides build-time transformations for styled-components library. This plugin operates as a WebAssembly-compiled transformation plugin for SWC, offering features like displayName generation for debugging, server-side rendering support, CSS minification, template literal processing, and JSX css prop transformation.
3

4
## Package Information
5

6
- **Package Name**: @swc/plugin-styled-components
7
- **Package Type**: npm
8
- **Language**: Rust (compiled to WebAssembly)
9
- **Installation**: `npm install --save-dev @swc/plugin-styled-components @swc/core`
10

11
## Core Imports
12

13
This plugin operates as a SWC transform plugin and is configured in the SWC configuration rather than imported directly in code:
14

15
```json
16
{
17
  "jsc": {
18
    "experimental": {
19
      "plugins": [
20
        ["@swc/plugin-styled-components", { /* options */ }]
21
      ]
22
    }
23
  }
24
}
25
```
26

27
## Basic Usage
28

29
Basic plugin configuration with common options:
30

31
```json
32
{
33
  "jsc": {
34
    "experimental": {
35
      "plugins": [
36
        [
37
          "@swc/plugin-styled-components",
38
          {
39
            "displayName": true,
40
            "ssr": true,
41
            "minify": true,
42
            "cssProp": true
43
          }
44
        ]
45
      ]
46
    }
47
  }
48
}
49
```
50

51
Example code transformation:
52

53
```javascript
54
// Input code
55
import styled from "styled-components";
56

57
const Button = styled.button`
58
  background: blue;
59
  color: white;
60
`;
61

62
// Output with displayName and SSR enabled
63
import styled from "styled-components";
64

65
const Button = styled.button.withConfig({
66
  displayName: "Button",
67
  componentId: "sc-1234567890"
68
})`background:blue;color:white;`;
69
```
70

71
## Capabilities
72

73
### Configuration Interface
74

75
Plugin configuration options control the transformation behavior. Note that configuration is provided as JSON in the SWC config file, using camelCase field names.
76

77
```typescript { .api }
78
interface Config {
79
  /** Add displayName for debugging (default: true) */
80
  displayName?: boolean;
81
  /** Enable server-side rendering support (default: true) */
82
  ssr?: boolean;
83
  /** Include filename in component ID (default: true) */
84
  fileName?: boolean;
85
  /** Files considered meaningless for naming (default: ["index"]) */
86
  meaninglessFileNames?: string[];
87
  /** Component namespace prefix (default: "") */
88
  namespace?: string;
89
  /** Import paths to process (default: []) */
90
  topLevelImportPaths?: string[];
91
  /** Transform template literals (default: true) */
92
  transpileTemplateLiterals?: boolean;
93
  /** Minify CSS in template literals (default: true) */
94
  minify?: boolean;
95
  /** Add pure annotations for dead code elimination (default: false) */
96
  pure?: boolean;
97
  /** Transform JSX css prop (default: true) */
98
  cssProp?: boolean;
99
}
100
```
101

102
**Configuration Examples:**
103

104
```json
105
// Full configuration with all options
106
{
107
  "jsc": {
108
    "experimental": {
109
      "plugins": [
110
        [
111
          "@swc/plugin-styled-components",
112
          {
113
            "displayName": true,
114
            "ssr": true,
115
            "fileName": true,
116
            "meaninglessFileNames": ["index", "styles"],
117
            "namespace": "myapp",
118
            "topLevelImportPaths": ["styled-components"],
119
            "transpileTemplateLiterals": true,
120
            "minify": true,
121
            "pure": false,
122
            "cssProp": true
123
          }
124
        ]
125
      ]
126
    }
127
  }
128
}
129

130
// Development configuration (enhanced debugging)
131
{
132
  "jsc": {
133
    "experimental": {
134
      "plugins": [
135
        [
136
          "@swc/plugin-styled-components",
137
          {
138
            "displayName": true,
139
            "ssr": false,
140
            "minify": false,
141
            "pure": false
142
          }
143
        ]
144
      ]
145
    }
146
  }
147
}
148

149
// Production configuration (optimized)
150
{
151
  "jsc": {
152
    "experimental": {
153
      "plugins": [
154
        [
155
          "@swc/plugin-styled-components",
156
          {
157
            "displayName": false,
158
            "ssr": true,
159
            "minify": true,
160
            "pure": true
161
          }
162
        ]
163
      ]
164
    }
165
  }
166
}
167
```
168

169
### Display Name Generation
170

171
Automatically adds displayName property to styled components for better debugging experience in React DevTools.
172

173
**Input:**
174
```javascript
175
import styled from "styled-components";
176

177
const Button = styled.button`
178
  padding: 8px 16px;
179
`;
180

181
const Header = styled.h1`
182
  font-size: 24px;
183
`;
184
```
185

186
**Output (with displayName: true):**
187
```javascript
188
import styled from "styled-components";
189

190
const Button = styled.button.withConfig({
191
  displayName: "Button"
192
})`padding:8px 16px;`;
193

194
const Header = styled.h1.withConfig({
195
  displayName: "Header"
196
})`font-size:24px;`;
197
```
198

199
**Configuration:**
200
- **Option**: `displayName: boolean`
201
- **Default**: `true`
202
- **Effect**: Adds displayName to withConfig() calls for debugging
203

204
### Server-Side Rendering (SSR) Support
205

206
Generates stable component IDs for consistent rendering between server and client.
207

208
**Input:**
209
```javascript
210
import styled from "styled-components";
211

212
const Container = styled.div`
213
  max-width: 1200px;
214
`;
215
```
216

217
**Output (with ssr: true):**
218
```javascript
219
import styled from "styled-components";
220

221
const Container = styled.div.withConfig({
222
  displayName: "Container",
223
  componentId: "sc-1a2b3c4d"
224
})`max-width:1200px;`;
225
```
226

227
**Configuration:**
228
- **Option**: `ssr: boolean`
229
- **Default**: `true` 
230
- **Effect**: Adds componentId based on file hash and component position
231

232
### CSS Minification
233

234
Minifies CSS content within template literals to reduce bundle size.
235

236
**Input:**
237
```javascript
238
const Button = styled.button`
239
  background: linear-gradient(
240
    to right,
241
    #ff6b6b,
242
    #4ecdc4
243
  );
244
  padding: 12px 24px;
245
  border-radius: 4px;
246
  border: none;
247
`;
248
```
249

250
**Output (with minify: true):**
251
```javascript
252
const Button = styled.button.withConfig({
253
  displayName: "Button",
254
  componentId: "sc-1a2b3c4d"
255
})`background:linear-gradient(to right,#ff6b6b,#4ecdc4);padding:12px 24px;border-radius:4px;border:none;`;
256
```
257

258
**Configuration:**
259
- **Option**: `minify: boolean`
260
- **Default**: `true`
261
- **Effect**: Removes unnecessary whitespace and optimizes CSS
262

263
### JSX CSS Prop Transformation
264

265
Transforms JSX css prop into styled components for runtime optimization.
266

267
**Input:**
268
```javascript
269
const MyComponent = () => (
270
  <div css="color: red; font-size: 16px;">
271
    Hello World
272
  </div>
273
);
274

275
const DynamicComponent = ({ color }) => (
276
  <p css={`color: ${color}; font-weight: bold;`}>
277
    Dynamic styling
278
  </p>
279
);
280
```
281

282
**Output (with cssProp: true):**
283
```javascript
284
const MyComponent = () => (
285
  <StyledDiv>
286
    Hello World
287
  </StyledDiv>
288
);
289

290
const DynamicComponent = ({ color }) => (
291
  <StyledP color={color}>
292
    Dynamic styling
293
  </StyledP>
294
);
295

296
const StyledDiv = styled.div`color:red;font-size:16px;`;
297
const StyledP = styled.p`color:${props => props.color};font-weight:bold;`;
298
```
299

300
**Configuration:**
301
- **Option**: `cssProp: boolean`
302
- **Default**: `true`
303
- **Effect**: Converts JSX css prop to styled components
304

305
### Pure Annotations
306

307
Adds /*#__PURE__*/ comments for dead code elimination by bundlers.
308

309
**Input:**
310
```javascript
311
import styled, { css, keyframes } from "styled-components";
312

313
const Button = styled.button`
314
  color: blue;
315
`;
316

317
const fadeIn = keyframes`
318
  from { opacity: 0; }
319
  to { opacity: 1; }
320
`;
321
```
322

323
**Output (with pure: true):**
324
```javascript
325
import styled, { css, keyframes } from "styled-components";
326

327
const Button = /*#__PURE__*/ styled.button.withConfig({
328
  displayName: "Button"
329
})`color:blue;`;
330

331
const fadeIn = /*#__PURE__*/ keyframes`
332
  from { opacity: 0; }
333
  to { opacity: 1; }
334
`;
335
```
336

337
**Configuration:**
338
- **Option**: `pure: boolean`
339
- **Default**: `false`
340
- **Effect**: Adds pure annotations for tree shaking
341

342
### Template Literal Processing
343

344
Processes and optimizes template literals in styled components.
345

346
**Configuration:**
347
- **Option**: `transpileTemplateLiterals: boolean`
348
- **Default**: `true`
349
- **Effect**: Transforms template literals for runtime optimization
350

351
### Namespace Support
352

353
Adds custom namespace prefix to component IDs for preventing conflicts.
354

355
**Configuration:**
356
- **Option**: `namespace: string`
357
- **Default**: `""`
358
- **Effect**: Adds namespace prefix to component IDs (e.g., "myapp__sc-1a2b3c4d")
359

360
**Example:**
361
```json
362
{
363
  "jsc": {
364
    "experimental": {
365
      "plugins": [
366
        [
367
          "@swc/plugin-styled-components",
368
          {
369
            "namespace": "myapp"
370
          }
371
        ]
372
      ]
373
    }
374
  }
375
}
376
```
377

378
### Filename Integration
379

380
Controls whether filename is included in component ID generation.
381

382
**Configuration:**
383
- **Option**: `fileName: boolean`
384
- **Default**: `true`
385
- **Effect**: Includes source filename in component ID calculation
386

387
### Meaningless File Names
388

389
Specifies filenames that should be ignored for component naming purposes.
390

391
**Configuration:**
392
- **Option**: `meaninglessFileNames: string[]`
393
- **Default**: `["index"]`
394
- **Effect**: Files with these names won't contribute to component naming
395

396
### Top-Level Import Paths
397

398
Specifies which import paths should be processed by the plugin.
399

400
**Configuration:**
401
- **Option**: `topLevelImportPaths: string[]`
402
- **Default**: `[]`
403
- **Effect**: Only process imports from specified paths
404

405
## Error Handling
406

407
The plugin will terminate the build process if:
408
- Invalid JSON configuration is provided
409
- Plugin configuration contains unknown fields (due to `deny_unknown_fields` setting)
410
- Required dependencies (@swc/core) are missing
411

412
Configuration errors result in build failures with descriptive messages from the SWC runtime. Ensure your plugin configuration follows the exact field names and types shown in the Config interface above.
413

414
## Dependencies
415

416
- **@swc/core**: Required for SWC transformation pipeline
417
- **@swc/counter**: Used for download telemetry
418

419
The plugin is distributed as a self-contained WebAssembly binary with no additional runtime dependencies required in the target project.
420

421
## Advanced Usage
422

423
### Conditional Configuration
424

425
```json
426
// Different configs per environment
427
{
428
  "env": {
429
    "development": {
430
      "jsc": {
431
        "experimental": {
432
          "plugins": [
433
            [
434
              "@swc/plugin-styled-components",
435
              {
436
                "displayName": true,
437
                "ssr": false,
438
                "minify": false
439
              }
440
            ]
441
          ]
442
        }
443
      }
444
    },
445
    "production": {
446
      "jsc": {
447
        "experimental": {
448
          "plugins": [
449
            [
450
              "@swc/plugin-styled-components",
451
              {
452
                "displayName": false,
453
                "ssr": true,
454
                "minify": true,
455
                "pure": true
456
              }
457
            ]
458
          ]
459
        }
460
      }
461
    }
462
  }
463
}
464
```
465

466
### Integration with Build Tools
467

468
**Next.js:**
469
```javascript
470
// next.config.js
471
module.exports = {
472
  experimental: {
473
    swcPlugins: [
474
      [
475
        "@swc/plugin-styled-components",
476
        {
477
          displayName: true,
478
          ssr: true
479
        }
480
      ]
481
    ]
482
  }
483
};
484
```
485

486
**Webpack with SWC:**
487
```javascript
488
// webpack.config.js
489
module.exports = {
490
  module: {
491
    rules: [
492
      {
493
        test: /\.(js|ts|jsx|tsx)$/,
494
        use: {
495
          loader: '@swc/loader',
496
          options: {
497
            jsc: {
498
              experimental: {
499
                plugins: [
500
                  [
501
                    "@swc/plugin-styled-components",
502
                    {
503
                      displayName: process.env.NODE_ENV === 'development',
504
                      ssr: true,
505
                      minify: process.env.NODE_ENV === 'production'
506
                    }
507
                  ]
508
                ]
509
              }
510
            }
511
          }
512
        }
513
      }
514
    ]
515
  }
516
};
517
```