web-infra-dev · keepview · Nov 19, 2025 · Nov 18, 2025 · Nov 18, 2025
diff --git a/.changeset/whole-numbers-visit.md b/.changeset/whole-numbers-visit.md
@@ -0,0 +1,6 @@
+---
+'@modern-js/plugin-styled-components': patch
+---
+
+feat: add styled-components plugin options and fix docs
+feat: styled-components 插件增加配置参数并修复相关文档
diff --git a/packages/cli/plugin-styled-components/src/index.ts b/packages/cli/plugin-styled-components/src/index.ts
@@ -1,24 +1,24 @@
 import type { AppTools, CliPlugin } from '@modern-js/app-tools';
-import { pluginStyledComponents } from '@rsbuild/plugin-styled-components';
+import {
+  type PluginStyledComponentsOptions,
+  pluginStyledComponents,
+} from '@rsbuild/plugin-styled-components';
 
-export const styledComponentsPlugin = (): CliPlugin<AppTools> => ({
+export const styledComponentsPlugin = (
+  options?: PluginStyledComponentsOptions,
+): CliPlugin<AppTools> => ({
   name: '@modern-js/plugin-styled-components',
 
   setup(api) {
     api.config(() => {
       return {
         builderPlugins: [
           pluginStyledComponents({
-            displayName: true,
-            minify: process.env.NODE_ENV === 'production',
+            ...options,
+            // https://github.com/styled-components/babel-plugin-styled-components/issues/287
+            topLevelImportPaths: ['@modern-js/plugin-styled-components/styled'],
           }),
         ],
-        tools: {
-          // styledComponents: {
-          //   // https://github.com/styled-components/babel-plugin-styled-components/issues/287
-          //   topLevelImportPaths: ['@modern-js/plugin-styled-components/styled'],
-          // },
-        },
         resolve: {
           alias: {
             'styled-components': require.resolve('styled-components'),

diff --git a/packages/document/docs/en/apis/app/runtime/utility/css-in-js.mdx b/packages/document/docs/en/apis/app/runtime/utility/css-in-js.mdx
@@ -1,14 +1,15 @@
 ---
 title: CSS-In-JS API
 ---
+
 # CSS-In-JS API
 
 Use Style Component to write CSS.
 
 ## Usage
 
 ```ts
-import styled from '@modern-js/runtime/styled';
+import styled from '@modern-js/plugin-styled-components/styled';
 ```
 
 ## Function Signature
@@ -18,7 +19,7 @@ see [styled-component API](https://styled-components.com/docs/api).
 ## Example
 
 ```tsx
-import styled from '@modern-js/runtime/styled';
+import styled from '@modern-js/plugin-styled-components/styled';
 
 const Button = styled.button`
   background: palevioletred;

diff --git a/packages/document/docs/en/configure/app/tools/styled-components.mdx b/packages/document/docs/en/configure/app/tools/styled-components.mdx
diff --git a/packages/document/docs/en/configure/app/tools/ts-loader.mdx b/packages/document/docs/en/configure/app/tools/ts-loader.mdx
@@ -6,7 +6,7 @@ title: tsLoader
 
 import { Badge } from '@theme';
 
-<Badge type="danger" >Webpack Only</Badge>
+<Badge type="danger">Webpack Only</Badge>
 
 - **Type:** `Object | Function | undefined`
 - **Default:** `undefined`
@@ -15,7 +15,7 @@ import { Badge } from '@theme';
 
 ts-loader is not recommended for use in the project, because:
 
-- ts-loader cannot be used with certain features such as [source.transformImport](/configure/app/source/transform-import) and [tools.styledComponents](/configure/app/tools/styled-components) provided by Babel & SWC.
+- ts-loader cannot be used with certain features such as [source.transformImport](/configure/app/source/transform-import)provided by Babel & SWC.
 - Rspack does not support ts-loader.
 
 :::

diff --git a/packages/document/docs/en/guides/advanced-features/low-level.mdx b/packages/document/docs/en/guides/advanced-features/low-level.mdx
@@ -30,13 +30,12 @@ When the value is `Function`, the first parameter is the default configuration v
 
 Currently provided is as follows:
 
-| Tools             | Config                                                           |
-| ----------------- | ---------------------------------------------------------------- |
-| DevServer         | [tools.devServer](/configure/app/tools/dev-server)               |
-| Babel             | [tools.babel](/configure/app/tools/babel)                        |
-| styled-components | [tools.styledComponents](/configure/app/tools/styled-components) |
-| PostCSS           | [tools.postcss](/configure/app/tools/postcss)                    |
-| Less              | [tools.less](/configure/app/tools/less)                          |
-| Sass              | [tools.sass](/configure/app/tools/sass)                          |
-| Minify CSS        | [tools.minifyCss](/configure/app/tools/minify-css)               |
-| Autoprefixer      | [tools.autoprefixer](/configure/app/tools/autoprefixer)          |
+| Tools        | Config                                                  |
+| ------------ | ------------------------------------------------------- |
+| DevServer    | [tools.devServer](/configure/app/tools/dev-server)      |
+| Babel        | [tools.babel](/configure/app/tools/babel)               |
+| PostCSS      | [tools.postcss](/configure/app/tools/postcss)           |
+| Less         | [tools.less](/configure/app/tools/less)                 |
+| Sass         | [tools.sass](/configure/app/tools/sass)                 |
+| Minify CSS   | [tools.minifyCss](/configure/app/tools/minify-css)      |
+| Autoprefixer | [tools.autoprefixer](/configure/app/tools/autoprefixer) |
diff --git a/packages/document/docs/en/guides/basic-features/css/css-in-js.mdx b/packages/document/docs/en/guides/basic-features/css/css-in-js.mdx
@@ -1,31 +1,34 @@
 # Using CSS-in-JS
 
-CSS-in-JS is a technique that allows you to write CSS styles in JS files.
+CSS-in-JS is a technique that allows you to write CSS styles within JS files.
 
-Modern.js supports the popular CSS-in-JS implementation library [styled-components](https://styled-components.com/), which uses the new JavaScript feature [Tagged template](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates) to write component CSS styles. You can directly import the API of [styled-components](https://styled-components.com/) from `@modern-js/runtime/styled` for use.
+Modern.js supports the commonly used community CSS-in-JS library [styled-components](https://styled-components.com/), which uses JavaScript's new feature [Tagged template](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates) to write component CSS styles.
+
+The Modern.js plugin `@modern-js/plugin-styled-components` provides support for styled-components and adds server-side rendering capability for styled-components. You can use styled-components by installing the `@modern-js/plugin-styled-components` plugin.
 
 ## Using styled-components in Modern.js
-First, you need to install the `styled-components` dependency:
 
-```bash
-# npm
-npm add @rsbuild/plugin-styled-components -D
+First, you need to install the `styled-components` plugin dependency:
 
-# yarn
-yarn add @rsbuild/plugin-styled-components -D
+import { PackageManagerTabs } from '@theme';
 
-# pnpm
-pnpm add @rsbuild/plugin-styled-components -D
-```
-Then, configure the `styled-components` plugin in `modern.config.ts`:
+<PackageManagerTabs
+  command={{
+    npm: 'npm install @modern-js/plugin-styled-components -D',
+    yarn: 'yarn add @modern-js/plugin-styled-components -D',
+    pnpm: 'pnpm install @modern-js/plugin-styled-components -D',
+  }}
+/>
+
+Then configure the `styled-components` plugin in `modern.config.ts`:
 
 ```ts
 import { defineConfig } from '@modern-js/app-tools';
-import { pluginStyledComponents } from '@rsbuild/plugin-styled-components';
+import { styledComponentsPlugin } from '@modern-js/plugin-styled-components';
 
 export default defineConfig({
-  builderPlugins: [
-    pluginStyledComponents({
+  plugins: [
+    styledComponentsPlugin({
       // ...
       displayName: true,
       minify: process.env.NODE_ENV === 'production',
@@ -34,33 +37,33 @@ export default defineConfig({
 });
 ```
 
-## Writing Styles with styled-components
+The configuration options of the styledComponentsPlugin plugin are the same as those of the [@rsbuild/plugin-styled-components](https://www.npmjs.com/package/@rsbuild/plugin-styled-components) plugin. You can refer to the documentation of [@rsbuild/plugin-styled-components](https://www.npmjs.com/package/@rsbuild/plugin-styled-components) for configuration.
 
-When you need to write a `div` component with an internal font color of red, you can implement it as follows:
+## Writing styles with styled-components
+
+When you need to write a `div` component with red text inside, you can implement it as follows:
 
 ```js
-import styled from '@modern-js/runtime/styled';
+import styled from '@modern-js/plugin-styled-components/styled';
 
 const RedDiv = styled.div`
   color: red;
 `;
 ```
 
-If you need to dynamically set component styles based on the component's `props`, for example, the `primary` property of `props` is `true`, the button color is white, otherwise it is red, you can implement the code as follows:
+When you need to dynamically set component styles based on the component's `props`, for example, when the `primary` attribute of `props` is `true`, the button's color is white, otherwise red, the implementation is as follows:
 
 ```js
-import styled from '@modern-js/runtime/styled';
+import styled from '@modern-js/plugin-styled-components/styled';
 
 const Button = styled.button`
   color: ${props => (props.primary ? 'white' : 'red')};
   font-size: 1em;
 `;
 ```
 
-For more usage of styled-components, please refer to [styled-components official website](https://styled-components.com/).
-
-Modern.js integrates Babel's [babel-plugin-styled-components](https://github.com/styled-components/babel-plugin-styled-components) plugin internally, and you can configure the plugin through [tools.styledComponents](/configure/app/tools/styled-components).
+For more usage of styled-components, please refer to the [styled-components official website](https://styled-components.com/).
 
-:::tip
-If you need to use other CSS-in-JS libraries such as [styled-jsx](https://www.npmjs.com/package/styled-jsx) and [Emotion](https://emotion.sh/), you need to install the corresponding dependencies first. For specific usage, please refer to the library's official website.
+:::tip Tip
+If you want to use other CSS-in-JS libraries such as [styled-jsx](https://www.npmjs.com/package/styled-jsx), [Emotion](https://emotion.sh/), etc., you need to install the corresponding dependencies first. Please refer to the official websites of the respective libraries for specific usage.
 :::
diff --git a/packages/document/docs/en/guides/troubleshooting/builder.mdx b/packages/document/docs/en/guides/troubleshooting/builder.mdx
@@ -188,20 +188,6 @@ export default {
 };
 ```
 
-In addition to the reasons mentioned above, there is another possibility that can cause Babel compilation to hang, which is when Babel compiles a large JS file exceeding 10,000 lines (usually a large file in the node_modules directory that is compiled using `source.include`).
-
-When Babel compiles large files, the built-in babel-plugin-styled-components in Modern.js can cause the compilation to hang. There is already a [relevant issue](https://github.com/styled-components/babel-plugin-styled-components/issues/374) in the community .
-
-In the future, Modern.js will consider removing the built-in babel-plugin-styled-components. In the current version, you can set [tools.styledComponents](/configure/app/tools/styled-components.html) to `false` to remove this plugin.
-
-```ts title="modern.config.ts"
-export default {
-  tools: {
-    styledComponents: false,
-  },
-};
-```
-
 ---
 
 ### The webpack cache does not work?