diff --git a/pages/docs.json b/pages/docs.json index fe3a0326..c6ee1464 100644 --- a/pages/docs.json +++ b/pages/docs.json @@ -101,6 +101,9 @@ { "title": "Babel Plugin" }, + { + "title": "SWC Plugin" + }, { "title": "Babel Macro" }, diff --git a/pages/docs/tooling.mdx b/pages/docs/tooling.mdx index 4eb1bab4..ae0cf858 100644 --- a/pages/docs/tooling.mdx +++ b/pages/docs/tooling.mdx @@ -2,6 +2,7 @@ import DocsLayout from '../../components/DocsLayout' import NextPage from '../../components/NextPage' import BabelPlugin from '../../sections/tooling/babel-plugin.mdx' +import SwcPlugin from '../../sections/tooling/swc-plugin.mdx' import BabelMacro from '../../sections/tooling/babel-macro.mdx' import TypeScriptPlugin from '../../sections/tooling/typescript-plugin.mdx' import Jest from '../../sections/tooling/jest.mdx' @@ -19,6 +20,7 @@ export default ({ children }) => ( ) + diff --git a/sections/tooling/swc-plugin.mdx b/sections/tooling/swc-plugin.mdx new file mode 100644 index 00000000..f7d2f9ee --- /dev/null +++ b/sections/tooling/swc-plugin.mdx @@ -0,0 +1,257 @@ +## SWC Plugin + +This plugin adds support for server-side rendering, minification of styles, and better debugging experience when using styled-components with the SWC compiler. + +### Usage + +First, install the `@swc/plugin-styled-components` and `@swc/core` packages: + +```bash +npm install --save-dev @swc/plugin-styled-components @swc/core +``` + +Then, add the plugin to your `.swcrc` configuration file: + +```json +{ + "jsc": { + "experimental": { + "plugins": [ + [ + "@swc/plugin-styled-components", + { + "displayName": true, + "ssr": true + } + ] + ] + } + } +} +``` + +### Options + +* `displayName`: + * 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. + * Type: Boolean + * Default: `true` + * Values: `true` or `false` +* `ssr`: + * 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). + * Type: Boolean + * Default: `true` + * Values: `true` or `false` +* `fileName`: + * Description: Controls whether the `displayName` of a component will be prefixed with the filename or solely the component name. + * Type: Boolean + * Default: `true` + * Values: `true` or `false` +* `meaninglessFileNames`: + * 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. + * Type: Array of strings + * Default: `["index", "styles"]` + * Values: Any array of strings representing meaningless file names. +* `minify`: + * Description: Minifies your CSS by removing all whitespace and comments. Also transpiles tagged template literals to a smaller representation. + * Type: Boolean + * Default: `true` + * Values: `true` or `false` +* `transpileTemplateLiterals`: + * Description: Transpiles `styled-components` tagged template literals to a smaller representation. Helps reduce bundle size. + * Type: Boolean + * Default: `true` + * Values: `true` or `false` +* `pure`: + * Description: Enables a feature called "pure annotation" to aid dead code elimination process on styled components. + * Type: Boolean + * Default: `false` + * Values: `true` or `false` +* `namespace`: + * Description: Ensures that your class names will be unique, useful when working with micro-frontends where class name collisions can occur. + * Type: String + * Default: `undefined` + * Values: Any string representing the desired namespace. + +### Server-side rendering + +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. + +You can disable this feature by setting the `ssr` option to `false`: + +```json +{ + "jsc": { + "experimental": { + "plugins": [ + [ + "@swc/plugin-styled-components", + { + "ssr": false + } + ] + ] + } + } +} +``` + +### Better Debugging + +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. + +If you don't need this feature, you can disable it by setting the `displayName` option to `false`: + +```json +{ + "jsc": { + "experimental": { + "plugins": [ + [ + "@swc/plugin-styled-components", + { + "displayName": false + } + ] + ] + } + } +} +``` + +#### Control the components `displayName` + +By default, the `displayName` of a component will be prefixed with the filename in order to make the component name as unique as possible. + +You can force the component `displayName` to be solely the component name by disabling the `fileName` option: + +```json +{ + "jsc": { + "experimental": { + "plugins": [ + [ + "@swc/plugin-styled-components", + { + "fileName": false + } + ] + ] + } + } +} +``` + +#### Control which file names are meaningless + +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 (`