Skip to content

Commit 13abba1

Browse files
rishabhkanojiyaRishabh Kanojiya
rishabhkanojiya
and
Rishabh Kanojiya
authored
Added Doc For SWC #907 (#967)
* ID: 907; MSG : added SWC plugin docs * ID: 907; MSG : updated snapshots --------- Co-authored-by: Rishabh Kanojiya <[email protected]>
1 parent f6ff6dc commit 13abba1

File tree

6 files changed

+308
-0
lines changed

6 files changed

+308
-0
lines changed

‎pages/docs.json

+3
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,9 @@
101101
{
102102
"title": "Babel Plugin"
103103
},
104+
{
105+
"title": "SWC Plugin"
106+
},
104107
{
105108
"title": "Babel Macro"
106109
},

‎pages/docs/tooling.mdx

+2
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ import DocsLayout from '../../components/DocsLayout'
22
import NextPage from '../../components/NextPage'
33

44
import BabelPlugin from '../../sections/tooling/babel-plugin.mdx'
5+
import SwcPlugin from '../../sections/tooling/swc-plugin.mdx'
56
import BabelMacro from '../../sections/tooling/babel-macro.mdx'
67
import TypeScriptPlugin from '../../sections/tooling/typescript-plugin.mdx'
78
import Jest from '../../sections/tooling/jest.mdx'
@@ -19,6 +20,7 @@ export default ({ children }) => (
1920
)
2021

2122
<BabelPlugin />
23+
<SwcPlugin />
2224
<BabelMacro />
2325
<TypeScriptPlugin />
2426
<Jest />

‎sections/tooling/swc-plugin.mdx

+257
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,257 @@
1+
## SWC Plugin
2+
3+
This plugin adds support for server-side rendering, minification of styles, and better debugging experience when using styled-components with the SWC compiler.
4+
5+
### Usage
6+
7+
First, install the `@swc/plugin-styled-components` and `@swc/core` packages:
8+
9+
```bash
10+
npm install --save-dev @swc/plugin-styled-components @swc/core
11+
```
12+
13+
Then, add the plugin to your `.swcrc` configuration file:
14+
15+
```json
16+
{
17+
"jsc": {
18+
"experimental": {
19+
"plugins": [
20+
[
21+
"@swc/plugin-styled-components",
22+
{
23+
"displayName": true,
24+
"ssr": true
25+
}
26+
]
27+
]
28+
}
29+
}
30+
}
31+
```
32+
33+
### Options
34+
35+
* `displayName`:
36+
* Description: Enhances the attached CSS class name on each component with richer output to help identify your components in the DOM without React DevTools. It also allows you to see the component's `displayName` in React DevTools.
37+
* Type: Boolean
38+
* Default: `true`
39+
* Values: `true` or `false`
40+
* `ssr`:
41+
* Description: Adds a unique identifier to every styled component to avoid checksum mismatches due to different class generation on the client and on the server. Helps in server-side rendering (SSR).
42+
* Type: Boolean
43+
* Default: `true`
44+
* Values: `true` or `false`
45+
* `fileName`:
46+
* Description: Controls whether the `displayName` of a component will be prefixed with the filename or solely the component name.
47+
* Type: Boolean
48+
* Default: `true`
49+
* Values: `true` or `false`
50+
* `meaninglessFileNames`:
51+
* Description: Allows customizing the list of file names that are not relevant to the description of a styled component's functionality. Uses directory names instead.
52+
* Type: Array of strings
53+
* Default: `["index", "styles"]`
54+
* Values: Any array of strings representing meaningless file names.
55+
* `minify`:
56+
* Description: Minifies your CSS by removing all whitespace and comments. Also transpiles tagged template literals to a smaller representation.
57+
* Type: Boolean
58+
* Default: `true`
59+
* Values: `true` or `false`
60+
* `transpileTemplateLiterals`:
61+
* Description: Transpiles `styled-components` tagged template literals to a smaller representation. Helps reduce bundle size.
62+
* Type: Boolean
63+
* Default: `true`
64+
* Values: `true` or `false`
65+
* `pure`:
66+
* Description: Enables a feature called "pure annotation" to aid dead code elimination process on styled components.
67+
* Type: Boolean
68+
* Default: `false`
69+
* Values: `true` or `false`
70+
* `namespace`:
71+
* Description: Ensures that your class names will be unique, useful when working with micro-frontends where class name collisions can occur.
72+
* Type: String
73+
* Default: `undefined`
74+
* Values: Any string representing the desired namespace.
75+
76+
### Server-side rendering
77+
78+
By adding a unique identifier to every styled component, this plugin avoids checksum mismatches due to different class generation on the client and on the server. If you don't use this plugin and try to server-side render styled components, React will complain with an HTML attribute mismatch warning during rehydration.
79+
80+
You can disable this feature by setting the `ssr` option to `false`:
81+
82+
```json
83+
{
84+
"jsc": {
85+
"experimental": {
86+
"plugins": [
87+
[
88+
"@swc/plugin-styled-components",
89+
{
90+
"ssr": false
91+
}
92+
]
93+
]
94+
}
95+
}
96+
}
97+
```
98+
99+
### Better Debugging
100+
101+
This option enhances the attached CSS class name on each component with richer output to help identify your components in the DOM without React DevTools. It also allows you to see the component's `displayName` in `React` DevTools.
102+
103+
If you don't need this feature, you can disable it by setting the `displayName` option to `false`:
104+
105+
```json
106+
{
107+
"jsc": {
108+
"experimental": {
109+
"plugins": [
110+
[
111+
"@swc/plugin-styled-components",
112+
{
113+
"displayName": false
114+
}
115+
]
116+
]
117+
}
118+
}
119+
}
120+
```
121+
122+
#### Control the components `displayName`
123+
124+
By default, the `displayName` of a component will be prefixed with the filename in order to make the component name as unique as possible.
125+
126+
You can force the component `displayName` to be solely the component name by disabling the `fileName` option:
127+
128+
```json
129+
{
130+
"jsc": {
131+
"experimental": {
132+
"plugins": [
133+
[
134+
"@swc/plugin-styled-components",
135+
{
136+
"fileName": false
137+
}
138+
]
139+
]
140+
}
141+
}
142+
}
143+
```
144+
145+
#### Control which file names are meaningless
146+
147+
A common pattern is to put components in `Button/index.jsx` instead of `Button.jsx`. By default, if the `fileName` option is set to `true`, the plugin will generate the `displayName` using the directory name (`<button class="Button-asdf123 asdf123" />`) instead of the file name (`<button class="index-asdf123 asdf123" />`), because the former provides more information.
148+
149+
The `meaninglessFileNames` option allows you to customize the list of file names that are not relevant to the description of a styled component's functionality, and hence the directory name should be used instead:
150+
151+
```json
152+
{
153+
"jsc": {
154+
"experimental": {
155+
"plugins": [
156+
[
157+
"@swc/plugin-styled-components",
158+
{
159+
"meaninglessFileNames": ["index", "styles"]
160+
}
161+
]
162+
]
163+
}
164+
}
165+
}
166+
```
167+
168+
### Minification
169+
170+
This plugin minifies your CSS by removing all whitespace and comments. It also transpiles tagged template literals to a smaller representation, keeping valuable bytes out of your bundles.
171+
172+
If desired, you can disable this behavior by setting the `minify` option to `false`:
173+
174+
```json
175+
{
176+
"jsc": {
177+
"experimental": {
178+
"plugins": [
179+
[
180+
"@swc/plugin-styled-components",
181+
{
182+
"minify": false,
183+
"transpileTemplateLiterals": false
184+
}
185+
]
186+
]
187+
}
188+
}
189+
}
190+
```
191+
192+
### Dead Code Elimination
193+
194+
Due to how styled components are transpiled and constructed, by default, minifiers cannot properly perform dead code elimination on them because they are assumed to have side effects. However, there is a feature that can be enabled to aid this process called "pure annotation".
195+
196+
```json
197+
{
198+
"jsc": {
199+
"experimental": {
200+
"plugins": [
201+
[
202+
"@swc/plugin-styled-components",
203+
{
204+
"pure": true
205+
}
206+
]
207+
]
208+
}
209+
}
210+
}
211+
```
212+
213+
### Template String Transpilation
214+
215+
Similar to the Babel plugin, this plugin transpiles `styled-components` tagged template literals to a smaller representation than what SWC normally creates. This helps reduce the bundle size.
216+
217+
You can disable this feature by setting the `transpileTemplateLiterals` option to `false`:
218+
219+
```json
220+
{
221+
"jsc": {
222+
"experimental": {
223+
"plugins": [
224+
[
225+
"@swc/plugin-styled-components",
226+
{
227+
"transpileTemplateLiterals": false
228+
}
229+
]
230+
]
231+
}
232+
}
233+
}
234+
```
235+
236+
### Namespace
237+
238+
The `namespace` option ensures that your class names will be unique, which is handy when working with micro-frontends where class name collisions can occur.
239+
240+
To enable this behavior, set the `namespace` option in your configuration:
241+
242+
```json
243+
{
244+
"jsc": {
245+
"experimental": {
246+
"plugins": [
247+
[
248+
"@swc/plugin-styled-components",
249+
{
250+
"namespace": "my-app"
251+
}
252+
]
253+
]
254+
}
255+
}
256+
}
257+
```

‎test/components/NavBar/__snapshots__/SidebarMenus.spec.tsx.snap

+10
Original file line numberDiff line numberDiff line change
@@ -356,6 +356,16 @@ exports[`DocsSidebarMenu renders correctly 1`] = `
356356
Babel Plugin
357357
</a>
358358
</h5>
359+
<h5
360+
className="c4"
361+
>
362+
<a
363+
className="c3"
364+
href="/docs/tooling#swc-plugin"
365+
>
366+
SWC Plugin
367+
</a>
368+
</h5>
359369
<h5
360370
className="c4"
361371
>

‎test/components/NavBar/__snapshots__/index.spec.tsx.snap

+18
Original file line numberDiff line numberDiff line change
@@ -1404,6 +1404,24 @@ exports[`Nav renders correctly 1`] = `
14041404
</styled.a>
14051405
</h5>
14061406
</styled.h5>
1407+
<styled.h5
1408+
key="SWC Plugin"
1409+
>
1410+
<h5
1411+
className="c25"
1412+
>
1413+
<styled.a
1414+
href="/docs/tooling#swc-plugin"
1415+
>
1416+
<a
1417+
className="c24"
1418+
href="/docs/tooling#swc-plugin"
1419+
>
1420+
SWC Plugin
1421+
</a>
1422+
</styled.a>
1423+
</h5>
1424+
</styled.h5>
14071425
<styled.h5
14081426
key="Babel Macro"
14091427
>

‎test/components/__snapshots__/DocsLayout.spec.tsx.snap

+18
Original file line numberDiff line numberDiff line change
@@ -1493,6 +1493,24 @@ exports[`DocsLayout renders correctly 1`] = `
14931493
</styled.a>
14941494
</h5>
14951495
</styled.h5>
1496+
<styled.h5
1497+
key="SWC Plugin"
1498+
>
1499+
<h5
1500+
className="c26"
1501+
>
1502+
<styled.a
1503+
href="/docs/tooling#swc-plugin"
1504+
>
1505+
<a
1506+
className="c25"
1507+
href="/docs/tooling#swc-plugin"
1508+
>
1509+
SWC Plugin
1510+
</a>
1511+
</styled.a>
1512+
</h5>
1513+
</styled.h5>
14961514
<styled.h5
14971515
key="Babel Macro"
14981516
>

0 commit comments

Comments
 (0)