@modern-js/main-doc 0.0.0-nightly-20240819170736 → 0.0.0-nightly-20240821170648

package/docs/en/configure/app/tools/esbuild.mdx

@@ -41,4 +41,4 @@ export default defineConfig({
 });
 ```
 
-For config details, please refer to [Modern.js Builder - Esbuild Plugin Configuration](https://modernjs.dev/builder/en/plugins/plugin-esbuild.html#config).
+For config details, please refer to [Esbuild Plugin Configuration](/guides/rsbuild-plugins/plugin-esbuild.html#config).

package/docs/en/configure/app/tools/swc.mdx

@@ -77,4 +77,4 @@ export default defineConfig({
 });
 ```
 
-For config details, please refer to [Modern.js Builder - SWC Plugin Configuration](https://modernjs.dev/builder/en/plugins/plugin-swc.html#config).
+For config details, please refer to [SWC Plugin Configuration](/guides/rsbuild-plugins/plugin-swc.html#config).

package/docs/en/guides/_meta.json

@@ -24,6 +24,11 @@
     "name": "topic-detail",
     "label": "topic"
   },
+  {
+    "type": "dir",
+    "name": "rsbuild-plugins",
+    "label": "Rsbuild Plugins"
+  },
   {
     "type": "dir",
     "name": "troubleshooting",

package/docs/en/guides/rsbuild-plugins/plugin-esbuild.mdx

@@ -0,0 +1,205 @@
+---
+sidebar_position: 3
+---
+
+# Esbuild Plugin
+
+:::warning
+**The esbuild feature in the current document is no longer maintained**, we recommend using the Rspack + SWC solution, because Rspack + SWC provide better build performance, richer features, and better compatibility.
+
+Please refer to [「Use Rspack」](guides/advanced-features/rspack-start) for more information.
+
+:::
+
+import Esbuild from '@modern-js/builder-doc/docs/en/shared/esbuild.md';
+
+<Esbuild />
+
+## Quick Start
+
+### Used in Modern.js framework
+
+The Modern.js framework integrates the Builder's esbuild plugin by default, so you don't need to manually install and register the plugin, just use the [tools.esbuild](https://modernjs.dev/en/configure/app/tools/esbuild.html) configuration:
+
+```js
+export default defineConfig({
+  tools: {
+    esbuild: {
+      loader: {
+        target: 'chrome61',
+      },
+      minimize: {
+        target: 'chrome61',
+      },
+    },
+  },
+});
+```
+
+## Config
+
+The plugin will enable code transformation and minification by default. You can also customize the behavior of the plugin through configuration.
+
+### loader
+
+- **Type:**
+
+```ts
+type LoaderOptions = EsbuildLoaderOptions | false | undefined;
+```
+
+- **Default:**
+
+```ts
+const defaultOptions = {
+  target: 'es2015',
+  charset: builderConfig.output.charset,
+};
+```
+
+This config is used to enable JavaScript/TypeScript transformation, which will replace babel-loader and ts-loader with esbuild-loader.
+
+If you want to modify the options, you can check the [esbuild-loader documentation](https://github.com/privatenumber/esbuild-loader#loader).
+
+#### Set JSX Format
+
+When using esbuild for transformation, esbuild will read the `compilerOptions.jsx` field in `tsconfig.json` to determine which JSX syntax to use.
+
+Therefore, you need to set the correct JSX syntax in `tsconfig.json`.
+
+For example, React projects need to set `compilerOptions.jsx` to `react-jsx`:
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx"
+  }
+}
+```
+
+#### Set the target environment
+
+Use the `target` option to set the target environment for transformation. `target` can be set directly to the JavaScript language version, such as `es6`, `es2020`; it can also be set to several target environments, each target environment is an environment name followed by a version number, such as `['chrome58', 'edge16' ,'firefox57']`. For a detailed introduction of the `target` option, please refer to [esbuild - target](https://esbuild.github.io/api/#target).
+
+target supports setting to the following environments:
+
+- chrome
+- edge
+- firefox
+- ie
+- ios
+- node
+- opera
+- safari
+
+```ts
+builderPluginEsbuild({
+  loader: {
+    target: 'chrome61',
+  },
+});
+```
+
+#### Disable transformation
+
+Set `loader` to `false` to disable esbuild transformation, and Builder will continue to use Babel to transform the code.
+
+```ts
+builderPluginEsbuild({
+  loader: false,
+});
+```
+
+### minimize
+
+- **Type:**
+
+```ts
+type MinimizeOptions = EsbuildMinifyOptions | false | undefined;
+```
+
+- **Default:**
+
+```ts
+const defaultOptions = {
+  css: true,
+  target: 'es2015',
+  format: builderTarget === 'web' ? 'iife' : undefined,
+};
+```
+
+This option is used to enable minification for JavaScript and CSS.
+
+If you want to modify the options, you can check the [esbuild-loader documentation](https://github.com/privatenumber/esbuild-loader#minifyplugin).
+
+#### Set the target environment
+
+Use the `target` option to set the target environment for minification.
+
+```ts
+builderPluginEsbuild({
+  minimize: {
+    target: 'chrome61',
+  },
+});
+```
+
+#### Disable minification
+
+Set `minimize` to `false` to disable esbuild minification, and Builder will continue to use Terser to minify the code.
+
+```ts
+builderPluginEsbuild({
+  minimize: false,
+});
+```
+
+## Limitations
+
+Although esbuild can significantly improve the build performance of existing webpack projects, it still has certain limitations that require special attention.
+
+### Compatibility
+
+As a compiler (i.e. `loader` capability), esbuild usually supports at least ES2015 (that is, ES6) syntax, and does not have the ability to automatically inject Polyfill.. If the production environment needs to downgrade to ES5 and below syntax, it is recommended to use SWC compilation.
+
+You can specify the target syntax version by following config:
+
+```ts
+builderPluginEsbuild({
+  loader: {
+    target: 'es2015',
+  },
+});
+```
+
+As a code minify tool (i.e. `minimize` capability), esbuild can minify the code in production environment, and usually supports ES2015 syntax at least.
+
+If you set the compressed `target` to `es5`, you need to ensure that all codes have been compiled to ES5 codes, otherwise it will cause esbuild compilation error: `Transforming 'xxx' to the configured target environment ("es5") is not supported yet `.
+
+Therefore, for projects that need to be compatible with ES5 and below syntax in the production environment, please be careful to enable the minimize capability, and it is recommended to use SWC compression.
+
+You can specify the target syntax version by following config:
+
+```js
+builderPluginEsbuild({
+  minimize: {
+    target: 'es2015',
+  },
+});
+```
+
+:::danger Caution
+Projects that need to be compatible with ES5 and below syntax in the production environment need to be careful to turn on the minimize config.
+:::
+
+### Not support Babel plugins
+
+As a compiler, the syntax transformation function of the original Babel plugins such as `babel-plugin-import` is not available after esbuild is turned on. And since the bottom layer of the plugin uses esbuild's `Transform API`, it does not support esbuild plugins to customize the compilation process.
+
+If you have requirements related to Babel plugins such as `babel-plugin-import`, you can use the SWC plugin.
+
+### Bundle Size
+
+Although the compression speed of esbuild is faster, the compression ratio of esbuild is lower than that of terser, so the bundle size will increase, please use it according to the scenes. Generally speaking, esbuild is more suitable for scenes that are not sensitive to bundle size.
+
+You can refer to [minification-benchmarks](https://github.com/privatenumber/minification-benchmarks) for a detailed comparison between minimizers.

package/docs/en/guides/rsbuild-plugins/plugin-swc.mdx

@@ -0,0 +1,356 @@
+---
+sidebar_position: 2
+---
+
+# SWC Plugin
+
+import SWC from '@modern-js/builder-doc/docs/en/shared/swc.md';
+
+<SWC />
+
+## Usage Scenarios
+
+Before using the SWC plugin, please understand the scenarios and limitations of the SWC plugin to determine whether your project is suitable for using it.
+
+### Rspack Scenario
+
+If you are already using Rspack as the bundler in your project, then you do not need to use the SWC plugin, because Rspack uses SWC for transpiler and minifier by default, and the SWC compilation capabilities are available out of the box.
+
+If you have configured the current SWC plugin when using Rspack, it will not have any effect.
+
+### Babel Plugins
+
+If your project requires the registration of some custom Babel plugins, you will not be able to register and use Babel plugins after using SWC, since it replaces Babel as the transpiler.
+
+For most common Babel plugins, you can find corresponding replacements in SWC, such as:
+
+- `@babel/preset-env`: use [presetEnv](#presetenv) instead.
+- `@babel/preset-react`: use [presetReact](#presetreact) instead.
+- `babel-plugin-import`: use [source.transformImport](/configure/app/source/transform-import) instead.
+- `babel-plugin-lodash`: use [extensions.lodash](#extensionslodash) instead.
+- `@emotion/babel-plugin`: use [extensions.emotion](#extensionsemotion) instead.
+- `babel-plugin-styled-components`: use [extensions.styledComponents](#extensionsstyledcomponents) instead.
+- `@babel/plugin-react-transform-remove-prop-types`: use [reactUtils.removePropTypes](#extensionsreactutils) instead.
+
+If you use Babel plugin capabilities that are not yet supported by SWC, you will no longer be able to use them after switching to SWC compilation. You can give feedback via issues under the [swc-plugins](https://github.com/web-infra-dev/swc-plugins) repository and we will evaluate if built-in support is needed.
+
+### Bundle Size
+
+When using SWC for code minification instead of [terser](https://github.com/terser/terser) and [cssnano](https://github.com/cssnano/cssnano), there may be a small change in the bundle size. SWC outperforms terser for JavaScript code compression and slightly underperforms cssnano for CSS code compression.
+
+For a detailed comparison between minifiers, see [minification-benchmarks](https://github.com/privatenumber/minification-benchmarks).
+
+## Quick Start
+
+### Used in Modern.js framework
+
+The Modern.js framework integrates the Builder's SWC plugin, and you can use it in the following ways:
+
+import EnableSWC from '@modern-js/builder-doc/docs/en/shared/enableSwc.md';
+
+<EnableSWC />
+
+That's it! Now you can use SWC transformation and minification in your project.
+
+## Config
+
+- **Type:**
+
+```ts
+type PluginConfig =
+  | ObjPluginConfig
+  | ((
+      config: ObjPluginConfig,
+      utils: { mergeConfig: typeof lodash.merge; setConfig: typeof lodash.set },
+    ) => ObjPluginConfig | void);
+
+// SwcOptions is configurations of swc https://swc.rs/docs/configuration/compilation
+interface ObjPluginConfig extends SwcOptions {
+  presetReact?: ReactConfig;
+  presetEnv?: EnvConfig;
+  jsMinify?: boolean | JsMinifyOptions;
+  cssMinify?: boolean | CssMinifyOptions;
+  extensions?: Extensions;
+  overrides?: Overrides;
+}
+```
+
+The plugin configuration is based on the SWC configuration. In order to simplify some deep-level configurations and improve development experience, certain extensions have been made. When using object-based configuration, for example you can use `presetReact` and `presetEnv` to quickly configure React-related features and syntax downgrading. Other configurations will also be directly passed through to SWC.
+
+When using function-based configuration, the default configuration generated by the plugin will be passed in, allowing you to modify it or return a new configuration.
+
+### presetReact
+
+- **Type:** [presetReact](https://swc.rs/docs/configuration/compilation#jsctransformreact) in SWC.
+
+Ported from `@babel/preset-react`. The value you passed will be merged with default option.
+
+By default, the plugin will set `runtime` field based on your `react` version, if `react` version is newer than 17.0.0, it will be set to `automatic`, otherwish `classic`.
+
+### presetEnv
+
+- **Type:** [presetEnv](https://swc.rs/docs/configuration/supported-browsers#options) in SWC.
+
+Ported from `@babel/preset-env`. The value you passed will be merged with default option.
+
+Default option is:
+
+```ts
+{
+  targets: '', // automatic get browserslist from your project, so you don't have to set this field
+  mode: 'usage',
+}
+```
+
+### jsMinify
+
+- **Type:** `boolean` or [compress configuration](https://terser.org/docs/api-reference.html#compress-options).
+- **Default:** `{ compress: {}, mangle: true }`.
+
+If set it to `false`, then SWC minification will be disabled, if set it to `true` then will it applies default option. If you pass an object, then this object will be merged with default option.
+
+### cssMinify
+
+- **Type:**: `boolean`
+- **Default:**: `true`
+
+Whether enable to compress CSS files by SWC. If enabled, it will improve the performance of CSS compression, but the compression ratio will be slightly reduced.
+
+### overrides
+
+- **Type:**
+
+```ts
+interface Overrides extends SwcOptions {
+  test: RegExp;
+  include: RegExp[];
+  exclude: RegExp[];
+}
+```
+
+- **Default:** `undefined`
+
+Specify special configuration for specific modules. For example if you want to set ie 11 target for `foo.ts`:
+
+```ts
+{
+  test: /foo.ts/,
+  env: { targets: 'ie 11' }
+}
+```
+
+This will merged into the default configuration, and do not affect other modules.
+
+### extensions
+
+- **Type:** `Object`
+
+Some plugins ported from Babel.
+
+#### extensions.reactUtils
+
+- **Type:** `Object`
+
+```ts
+type ReactUtilsOptions = {
+  autoImportReact?: boolean;
+  removeEffect?: boolean;
+  removePropTypes?: {
+    mode?: 'remove' | 'unwrap' | 'unsafe-wrap';
+    removeImport?: boolean;
+    ignoreFilenames?: string[];
+    additionalLibraries?: string[];
+    classNameMatchers?: string[];
+  };
+};
+```
+
+Some little help utils for `React`.
+
+**reactUtils.autoImportReact**
+
+- **Type:** `boolean`
+
+Automatically import `React` as global variable, eg: `import React from 'react'`.
+Mostly used for generated `React.createElement`.
+
+**reactUtils.removeEffect**
+
+- **Type:** `boolean`
+
+Remove `useEffect` call.
+
+**reactUtils.removePropTypes**
+
+- **Type:**
+
+```ts
+type RemovePropTypesOptions = {
+  mode?: 'remove' | 'unwrap' | 'unsafe-wrap';
+  removeImport?: boolean;
+  ignoreFilenames?: string[];
+  additionalLibraries?: string[];
+  classNameMatchers?: string[];
+};
+```
+
+Remove `React` runtime type checking. This is ported from [@babel/plugin-react-transform-remove-prop-types](https://github.com/oliviertassinari/babel-plugin-transform-react-remove-prop-types), All the configurations remain the same.
+
+#### extensions.lodash
+
+- **Type:**
+
+```ts
+type LodashOptions = {
+  cwd?: string;
+  ids?: string[];
+};
+```
+
+- **Default:**
+
+```ts
+const defaultOptions = {
+  cwd: process.cwd(),
+  ids: ['lodash', 'lodash-es'],
+};
+```
+
+Ported from [babel-plugin-lodash](https://github.com/lodash/babel-plugin-lodash), it is used to automatically convert references to Lodash into on-demand imports, thereby reducing the bundle size of Lodash code.
+
+```ts
+// Input
+import { get, throttle } from 'lodash';
+
+// Output
+import get from 'lodash/get';
+import throttle from 'lodash/throttle';
+```
+
+#### extensions.styledComponents
+
+- **Type:**
+
+```ts
+boolean | {
+  // Enabled by default in development, disabled in production to reduce file size,
+  // setting this will override the default for all environments.
+  displayName?: boolean,
+  // Enabled by default.
+  ssr?: boolean,
+  // Enabled by default.
+  fileName?: boolean,
+  // Empty by default.
+  topLevelImportPaths?: string[],
+  // Defaults to ["index"].
+  meaninglessFileNames?: string[],
+  // Enabled by default.
+  cssProp?: boolean,
+  // Empty by default.
+  namespace?: string,
+};
+```
+
+This is ported by Next.js team from [babel-plugin-styled-components](https://github.com/styled-components/babel-plugin-styled-components).
+
+#### extensions.emotion
+
+- **Type:**
+
+```ts
+boolean | {
+  // default is true. It will be disabled when build type is production.
+  sourceMap?: boolean,
+  // default is 'dev-only'.
+  autoLabel?: 'never' | 'dev-only' | 'always',
+  // default is '[local]'.
+  // Allowed values: `[local]` `[filename]` and `[dirname]`
+  // This option only works when autoLabel is set to 'dev-only' or 'always'.
+  // It allows you to define the format of the resulting label.
+  // The format is defined via string where variable parts are enclosed in square brackets [].
+  // For example labelFormat: "my-classname--[local]", where [local] will be replaced with the name of the variable the result is assigned to.
+  labelFormat?: string,
+  // default is undefined.
+  // This option allows you to tell the compiler what imports it should
+  // look at to determine what it should transform so if you re-export
+  // Emotion's exports, you can still use transforms.
+  importMap?: {
+    [packageName: string]: {
+      [exportName: string]: {
+        canonicalImport?: [string, string],
+        styledBaseImport?: [string, string],
+      }
+    }
+  },
+}
+```
+
+This is ported by Next.js team from [@emotion/babel-plugin](https://www.npmjs.com/package/@emotion/babel-plugin)
+
+#### extensions.pluginImport
+
+:::tip
+Builder provides the [source.transformImport](/configure/app/source/transform-import) config, so you don't need to configure `extensions.pluginImport` manually.
+:::
+
+Ported from [babel-plugin-import](https://github.com/umijs/babel-plugin-import), configurations are the same.
+
+Some configurations can be passed in functions, such as `customName`, `customStyleName`. These JavaScript functions will be called by Rust through Node-API, which will cause some performance overhead.
+
+Some simple function logic can be replaced by template language. Therefore, the configuration of function items such as `customName`, `customStyleName` can also be passed in strings as templates to replace functions and improve performance.
+
+For example:
+
+```ts
+import { MyButton as Btn } from 'foo';
+```
+
+Apply following configurations:
+
+```ts
+PluginSWC({
+  extensions: {
+    pluginImport: [
+      {
+        libraryName: 'foo',
+        customName: 'foo/es/{{ member }}',
+      },
+    ],
+  },
+});
+```
+
+`{{ member }}` will be replaced by the imported specifier:
+
+```ts
+import Btn from 'foo/es/MyButton';
+```
+
+Template `customName: 'foo/es/{{ member }}'` is the same as `` customName: (member) => `foo/es/${member}`  ``, but template value has no performance overhead of Node-API.
+
+The template used here is [handlebars](https://handlebarsjs.com). There are some useful builtin tools, Take the above import statement as an example:
+
+```ts
+PluginSWC({
+  extensions: {
+    pluginImport: [
+      {
+        libraryName: 'foo',
+        customName: 'foo/es/{{ kebabCase member }}',
+      },
+    ],
+  },
+});
+```
+
+Transformed to:
+
+```ts
+import Btn from 'foo/es/my-button';
+```
+
+In addition to `kebabCase`, there are `cameraCase`, `snakeCase`, `upperCase` and `lowerCase` can be used as well.
+
+## Limitation
+
+Do not support `@babel/plugin-transform-runtime` and other custom Babel plugins.

package/docs/zh/configure/app/tools/esbuild.mdx

@@ -41,4 +41,4 @@ export default defineConfig({
 });
 ```
 
-完整配置项请参考 [Modern.js Builder - esbuild 插件配置](https://modernjs.dev/builder/plugins/plugin-esbuild.html#%E9%85%8D%E7%BD%AE)。
+完整配置项请参考 [esbuild 插件配置](/guides/rsbuild-plugins/plugin-esbuild.html#配置)。

package/docs/zh/configure/app/tools/swc.mdx

@@ -77,4 +77,4 @@ export default defineConfig({
 });
 ```
 
-完整配置项请参考 [Modern.js Builder - SWC 插件配置](https://modernjs.dev/builder/plugins/plugin-swc.html#%E9%85%8D%E7%BD%AE)。
+完整配置项请参考 [SWC 插件配置](/guides/rsbuild-plugins/plugin-swc.html#配置)。

package/docs/zh/guides/_meta.json

@@ -24,6 +24,11 @@
     "name": "topic-detail",
     "label": "topic"
   },
+  {
+    "type": "dir",
+    "name": "rsbuild-plugins",
+    "label": "构建插件"
+  },
   {
     "type": "dir",
     "name": "troubleshooting",

package/docs/zh/guides/rsbuild-plugins/plugin-esbuild.mdx

@@ -0,0 +1,201 @@
+---
+sidebar_position: 3
+---
+
+# Esbuild 插件
+
+:::warning
+**当前文档中的 esbuild 功能已停止迭代**，我们更推荐使用 Rspack + SWC 的方案，因为 Rspack + SWC 具备更好的构建性能、功能丰富度和产物兼容性。
+
+请参考[「使用 Rspack」](guides/advanced-features/rspack-start)了解更多。
+
+:::
+
+import Esbuild from '@modern-js/builder-doc/docs/zh/shared/esbuild.md';
+
+<Esbuild />
+
+## 快速开始
+
+### 在 Modern.js 框架中使用
+
+Modern.js 框架默认集成了 Builder 的 esbuild 插件，因此，你不需要手动安装和注册插件，只需要使用 [tools.esbuild](/configure/app/tools/esbuild.html) 配置项即可：
+
+```js
+export default defineConfig({
+  tools: {
+    esbuild: {
+      loader: {
+        target: 'chrome61',
+      },
+      minimize: {
+        target: 'chrome61',
+      },
+    },
+  },
+});
+```
+
+## 配置
+
+插件默认会开启代码转译和代码压缩的功能，你也可以通过配置来自定义插件的行为。
+
+### loader
+
+- **类型：**
+
+```ts
+type LoaderOptions = EsbuildLoaderOptions | false | undefined;
+```
+
+- **默认值：**
+
+```ts
+const defaultOptions = {
+  target: 'es2015',
+  charset: builderConfig.output.charset,
+};
+```
+
+这个选项用于启用 JavaScript 和 TypeScript 的转译，启用时将会使用 esbuild-loader 替换 babel-loader 和 ts-loader。
+
+如果你需要修改转译参数，可以查看 [esbuild-loader 文档](https://github.com/privatenumber/esbuild-loader#loader)。
+
+#### 设置 JSX 格式
+
+在使用 esbuild 进行代码转译时，esbuild 默认会读取 `tsconfig.json` 中的 `compilerOptions.jsx` 字段，来决定使用哪种 JSX 语法。
+
+因此，你需要在 `tsconfig.json` 中设置正确的 JSX 语法。
+
+比如 React 项目，需要将 `compilerOptions.jsx` 设置为 `react-jsx`：
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx"
+  }
+}
+```
+
+#### 修改目标环境
+
+通过 `target` 选项来修改代码转译的目标环境。`target` 可以直接设置为 JavaScript 语言版本，比如 `es6`，`es2020`；也可以设置为若干个目标环境，每个目标环境都是一个环境名称后跟一个版本号，比如 `['chrome58', 'edge16' ,'firefox57']`。`target` 字段的详细介绍可以参考 [esbuild - target](https://esbuild.github.io/api/#target)。
+
+target 支持设置为以下环境：
+
+- chrome
+- edge
+- firefox
+- ie
+- ios
+- node
+- opera
+- safari
+
+```ts
+builderPluginEsbuild({
+  loader: {
+    target: 'chrome61',
+  },
+});
+```
+
+#### 关闭代码转译
+
+将 `loader` 设置为 `false` 来关闭 esbuild 代码转译，此时 Builder 会继续使用 Babel 来进行代码转译。
+
+```ts
+builderPluginEsbuild({
+  loader: false,
+});
+```
+
+### minimize
+
+- **类型：**
+
+```ts
+type MinimizeOptions = EsbuildMinifyOptions | false | undefined;
+```
+
+- **默认值：**
+
+```ts
+const defaultOptions = {
+  css: true,
+  target: 'es2015',
+  format: builderTarget === 'web' ? 'iife' : undefined,
+};
+```
+
+这个选项用于启用 JavaScript 和 CSS 的代码压缩。
+
+如果你需要修改压缩参数，可以查看 [esbuild-loader 文档](https://github.com/privatenumber/esbuild-loader#minifyplugin)。
+
+#### 修改目标环境
+
+通过 `target` 选项来修改代码压缩的目标环境。
+
+```ts
+builderPluginEsbuild({
+  minimize: {
+    target: 'chrome61',
+  },
+});
+```
+
+#### 关闭代码压缩
+
+将 `minimize` 设置为 `false` 来关闭 esbuild 代码压缩，此时 Builder 会继续使用 Terser 进行代码压缩。
+
+```ts
+builderPluginEsbuild({
+  minimize: false,
+});
+```
+
+## esbuild 局限性
+
+虽然 esbuild 能给现有的 webpack 项目带来明显的构建性能提升，但这个工具在接入 Builder 时还存在一定的局限性，需要大家在接入的时候格外注意。
+
+### 兼容性
+
+使用 esbuild 进行代码转译时（即 `loader` 能力），esbuild 通常最低支持到 ES2015（即 ES6）语法，并且不具备自动注入 Polyfill 的能力。如果生产环境需要降级到 ES5 及以下的语法，建议使用 SWC 编译。
+
+你可以通过如下的配置指定目标语法版本:
+
+```ts
+builderPluginEsbuild({
+  loader: {
+    target: 'es2015',
+  },
+});
+```
+
+使用 esbuild 进行代码压缩时（即 `minimize` 能力），esbuild 可以在生产环境中进行压缩和混淆，通常最低支持到 ES2015 语法。
+
+如果设置压缩的 `target` 为 `es5`，需要保证所有代码已经被转义为 ES5 代码，否则会导致 esbuild 编译报错：`Transforming 'xxx' to the configured target environment ("es5") is not supported yet`。
+
+因此，对于生产环境需要兼容 ES5 及以下语法的项目，请谨慎开启 minimize 能力，建议使用 SWC 压缩。
+
+你可以通过如下的配置指定目标语法版本:
+
+```ts
+builderPluginEsbuild({
+  minimize: {
+    target: 'es2015',
+  },
+});
+```
+
+### 不支持 Babel 插件
+
+使用 esbuild 进行代码转译时，诸如 `babel-plugin-import` 等原有 Babel 插件的语法编译功能在开启 esbuild 后无法使用。并且由于 Builder 底层使用的是 esbuild 的 `Transform API`，因此不支持使用额外 esbuild 插件来进行自定义编译过程。
+
+如果你有 `babel-plugin-import` 等 Babel 插件相关诉求，可以使用 SWC 插件。
+
+### 产物体积
+
+使用 esbuild 压缩虽然带来了构建效率上的提升，但 esbuild 的压缩比例是低于 terser 的，因此**构建产物的体积会增大**，请根据业务情况酌情使用。通常来说，esbuild 比较适合中后台等对体积不敏感的场景。
+
+对于压缩工具之间的详细对比，可以参考 [minification-benchmarks](https://github.com/privatenumber/minification-benchmarks)。

package/docs/zh/guides/rsbuild-plugins/plugin-swc.mdx

@@ -0,0 +1,344 @@
+---
+sidebar_position: 2
+---
+
+# SWC 插件
+
+import SWC from '@modern-js/builder-doc/docs/zh/shared/swc.md';
+
+<SWC />
+
+## 适用场景
+
+在使用 SWC 插件之前，请先了解一下 SWC 插件的适用场景和局限性，以明确你的项目是否需要使用 SWC 插件。
+
+### Rspack 场景
+
+如果你的项目中已经使用了 Rspack 作为打包工具，那么你不需要接入 SWC 插件，因为 Rspack 默认会使用 SWC 进行转译和压缩，各个 SWC 编译能力可以开箱即用。
+
+如果你使用 Rspack 时配置了当前的 SWC 插件，它将不会产生任何效果。
+
+### Babel 插件
+
+如果你的项目需要注册一些自定义的 Babel 插件，由于 SWC 替代了 Babel 作为转译工具，因此使用 SWC 后，你将无法注册和使用 Babel 插件。
+
+对于大部分常见的 Babel 插件，你可以在 SWC 中找到对应的替代品，比如：
+
+- `@babel/preset-env`: 使用 [presetEnv](#presetenv) 代替。
+- `@babel/preset-react`: 使用 [presetReact](#presetreact) 代替。
+- `babel-plugin-import`：使用 [source.transformImport](/configure/app/source/transform-import) 代替。
+- `babel-plugin-lodash`：使用 [extensions.lodash](#extensionslodash) 代替。
+- `@emotion/babel-plugin`：使用 [extensions.emotion](#extensionsemotion) 代替。
+- `babel-plugin-styled-components`：使用 [extensions.styledComponents](#extensionsstyledcomponents) 代替。
+- `@babel/plugin-react-transform-remove-prop-types`: 使用 [reactUtils.removePropTypes](#extensionsreactutils) 代替。
+
+如果你使用了 SWC 尚未支持的 Babel 插件能力，在切换到 SWC 编译后，将无法再使用它们。你可以到 [swc-plugins](https://github.com/web-infra-dev/swc-plugins) 仓库下通过 issues 进行反馈，我们会评估是否需要内置支持。
+
+### 产物体积
+
+在使用 SWC 来代替 [terser](https://github.com/terser/terser) 和 [cssnano](https://github.com/cssnano/cssnano) 进行代码压缩时，构建产物的体积可能会出现少量变化。在 JavaScript 代码压缩方面，SWC 的压缩率是优于 terser 的；在 CSS 代码压缩方面，SWC 的压缩率稍逊于 cssnano。
+
+对于压缩工具之间的详细对比，可以参考 [minification-benchmarks](https://github.com/privatenumber/minification-benchmarks)。
+
+## 快速开始
+
+### 在 Modern.js 框架中使用
+
+Modern.js 框架对 Builder 的 SWC 插件进行了封装，你可以通过以下方式来使用：
+
+import EnableSWC from '@modern-js/builder-doc/docs/zh/shared/enableSwc.md';
+
+<EnableSWC />
+
+That's it! 现在你可以在项目中无缝使用 SWC 的转译和压缩能力了。
+
+## 配置
+
+- **类型：**
+
+```ts
+type PluginConfig =
+  | ObjPluginConfig
+  | ((
+      config: ObjPluginConfig,
+      utils: { mergeConfig: typeof lodash.merge; setConfig: typeof lodash.set },
+    ) => ObjPluginConfig | void);
+
+// SwcOptions 为 swc 配置项 https://swc.rs/docs/configuration/compilation
+interface ObjPluginConfig extends SwcOptions {
+  presetReact?: ReactConfig;
+  presetEnv?: EnvConfig;
+  jsMinify?: boolean | JsMinifyOptions;
+  cssMinify?: boolean | CssMinifyOptions;
+  extensions?: Extensions;
+  overrides?: Overrides;
+}
+```
+
+插件配置在 SWC 配置的基础上，为了简化部分深层配置和为提高开发体验，进行了部分拓展，例如当使用对象形式配置时，可以使用 `presetReact` 以及 `presetEnv` 快速配置 react 以及语法降级相关功能，另外不属于插件特有的配置也会直接透传给 swc。
+
+当使用函数形式配置时，则会传入插件内部产出的默认配置，可以对其进行修改或返回新的配置。
+
+### presetReact
+
+- **类型：** SWC 中的 [react](https://swc.rs/docs/configuration/compilation#jsctransformreact) 配置。
+
+对标 `@babel/preset-react`。传入的值会与默认配置进行合并。
+
+插件默认会自动根据你的 `react` 版本确定 `runtime` 字段，如果 `react` 版本大于 17.0.0，会设置成 `automatic`，否则设置成 `classic`。
+
+### presetEnv
+
+- **类型：** SWC 中的 [presetEnv](https://swc.rs/docs/configuration/supported-browsers#options)。
+
+对标 `@babel/preset-env`。传入的值会与默认配置进行合并。
+默认配置为:
+
+```ts
+{
+  targets: '', // 自动从项目中获取 browserslist
+  mode: 'usage',
+}
+```
+
+### jsMinify
+
+- **类型：** `boolean` 或者 [terser 中的 compress 配置](https://terser.org/docs/api-reference.html#compress-options)。
+- **默认值：** `{ compress: {}, mangle: true }`。
+
+如果配置 `false` 将不会使用 SWC 的压缩能力，配置 `true` 会启用默认压缩配置，如果配置是对象，则会与默认配置进行合并。
+
+### cssMinify
+
+- **类型：** `boolean`
+- **默认值：** `true`
+
+是否启用 SWC 对 CSS 文件进行压缩，若启用会使得 CSS 压缩性能提高，但压缩率会略微降低。
+
+### overrides
+
+- **类型：**
+
+```ts
+interface Overrides extends SwcOptions {
+  test: RegExp;
+  include: RegExp[];
+  exclude: RegExp[];
+}
+```
+
+- **默认值：** `undefined`
+
+对指定文件运用另外的配置。例如需要对 `foo.ts` 的语法降级成 ie 11，则可以如下配置：
+
+```ts
+{
+  test: /foo.ts/,
+  env: { targets: 'ie 11' }
+}
+```
+
+该配置会与默认配置进行合并，并且不会影响到其他文件。
+
+### extensions
+
+- **类型：** `Object`
+
+`extensions` 包含了从 Babel 移植过来的一些插件能力。
+
+#### extensions.reactUtils
+
+- **类型：**
+
+```ts
+type ReactUtilsOptions = {
+  autoImportReact?: boolean;
+  removeEffect?: boolean;
+  removePropTypes?: {
+    mode?: 'remove' | 'unwrap' | 'unsafe-wrap';
+    removeImport?: boolean;
+    ignoreFilenames?: string[];
+    additionalLibraries?: string[];
+    classNameMatchers?: string[];
+  };
+};
+```
+
+一些用于 `React` 的工具，包括以下配置项:
+
+**reactUtils.autoImportReact**
+
+- **类型：** `boolean`
+
+自动引入 `React`, `import React from 'react'`，用于 `jsx` 转换使用 `React.createElement`。
+
+**reactUtils.removeEffect**
+
+- **类型：** `boolean`
+
+移除 `useEffect` 调用。
+
+**reactUtils.removePropTypes**
+
+- **类型：**
+
+```ts
+type RemovePropTypesOptions = {
+  mode?: 'remove' | 'unwrap' | 'unsafe-wrap';
+  removeImport?: boolean;
+  ignoreFilenames?: string[];
+  additionalLibraries?: string[];
+  classNameMatchers?: string[];
+};
+```
+
+移除 `React` 组件在运行时的类型判断。移植自 [@babel/plugin-react-transform-remove-prop-types](https://github.com/oliviertassinari/babel-plugin-transform-react-remove-prop-types)。
+
+相应配置和 `@babel/plugin-react-transform-remove-prop-types` 插件保持一致。
+
+#### extensions.lodash
+
+- **类型：**
+
+```ts
+type LodashOptions = {
+  cwd?: string;
+  ids?: string[];
+};
+```
+
+- **默认值：**
+
+```ts
+const defaultOptions = {
+  cwd: process.cwd(),
+  ids: ['lodash', 'lodash-es'],
+};
+```
+
+移植自 [babel-plugin-lodash](https://github.com/lodash/babel-plugin-lodash)，用于自动将 Lodash 的引用转换为按需引入，从而减少打包后的 Lodash 代码大小。
+
+```ts
+// Input
+import { get, throttle } from 'lodash';
+
+// Output
+import get from 'lodash/get';
+import throttle from 'lodash/throttle';
+```
+
+#### extensions.styledComponents
+
+- **类型：**
+
+```ts
+boolean | {
+  displayName?: boolean; // 默认开发模式开启, 生产模式关闭,
+  ssr?: boolean; // 默认开启
+  fileName?: boolean; // 默认开启
+  topLevelImportPaths?: string[]; // 默认空
+  meaninglessFileNames?: string[]; // 默认为 ["index"].
+  cssProp?: boolean; // 默认开启
+  namespace?: string; // 默认空
+};
+```
+
+由 Next.js 团队移植自 [babel-plugin-styled-components](https://github.com/styled-components/babel-plugin-styled-components)。
+
+#### extensions.emotion
+
+- **类型：**
+
+```ts
+boolean | {
+  sourceMap?: boolean, // 默认开启
+  autoLabel?: 'never' | 'dev-only' | 'always', // 默认 'dev-only'
+  // 默认 '[local]'.
+  // 允许的值为: `[local]` `[filename]` 以及 `[dirname]`
+  // 只有当 autoLabel 设置成 'dev-only' 或者 'always' 才会生效.
+  // 该配置允许你定义结果标签的格式，该格式的组成是字符串以及可以由方括号包裹字符串作为变量
+  // 例如对于 "my-classname--[local]"，其中的 [local] 会被替换成相应的变量
+  labelFormat?: string,
+  // 默认值 undefined.
+  // 该配置允许让编译器知道哪一个引入需要进行转换，所以如果你重导出了 emotion
+  // 的导出，你仍然可以使用该插件进行转换
+  importMap?: {
+    [packageName: string]: {
+      [exportName: string]: {
+        canonicalImport?: [string, string],
+        styledBaseImport?: [string, string],
+      }
+    }
+  },
+},
+```
+
+由 Next.js 团队移植自 [@emotion/babel-plugin](https://www.npmjs.com/package/@emotion/babel-plugin)。
+
+#### extensions.pluginImport
+
+:::tip
+Builder 提供了 [source.transformImport](/configure/app/source/transform-import) 配置项，因此你不需要手动配置 `extensions.pluginImport`。
+:::
+
+移植自 [babel-plugin-import](https://github.com/umijs/babel-plugin-import)，配置选项保持一致。
+
+一些配置可以传入函数，例如 `customName`，`customStyleName` 等，这些 JavaScript 函数会由 Rust 通过 Node-API 调用，这种调用会造成一些性能劣化。
+
+简单的函数逻辑其实可以通过模版语言来代替，因此`customName`，`customStyleName` 等这些配置除了可以传入函数，也可以传入字符串作为模版来代替函数，提高性能。
+
+我们以下面代码为例说明:
+
+```ts
+import { MyButton as Btn } from 'foo';
+```
+
+添加以下配置：
+
+```ts
+PluginSWC({
+  extensions: {
+    pluginImport: [
+      {
+        libraryName: 'foo',
+        customName: 'foo/es/{{ member }}',
+      },
+    ],
+  },
+});
+```
+
+其中的 `{{ member }}` 会被替换为相应的引入成员，转换后:
+
+```ts
+import Btn from 'foo/es/MyButton';
+```
+
+可以看出配置 `customName: "foo/es/{{ member }}"` 的效果等同于配置 `` customName: (member) => `foo/es/${member}`  ``，但是不会有 Node-API 的调用开销。
+
+这里使用到的模版是 [handlebars](https://handlebarsjs.com)，模版配置中还内置了一些有用的辅助工具，还是以上面的导入语句为例，配置成：
+
+```ts
+PluginSWC({
+  extensions: {
+    pluginImport: [
+      {
+        libraryName: 'foo',
+        customName: 'foo/es/{{ kebabCase member }}',
+      },
+    ],
+  },
+});
+```
+
+会转换成下面的结果:
+
+```ts
+import Btn from 'foo/es/my-button';
+```
+
+除了 `kebabCase` 以外还有 `camelCase`，`snakeCase`，`upperCase`，`lowerCase` 可以使用。
+
+## 限制
+
+不支持 `@babel/plugin-transform-runtime` 以及其他自定义的 Babel 插件。

package/package.json

@@ -15,17 +15,17 @@
     "modern",
     "modern.js"
   ],
-  "version": "0.0.0-nightly-20240819170736",
+  "version": "0.0.0-nightly-20240821170648",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public",
     "provenance": true
   },
   "dependencies": {
-    "@modern-js/sandpack-react": "0.0.0-nightly-20240819170736"
+    "@modern-js/sandpack-react": "0.0.0-nightly-20240821170648"
   },
   "peerDependencies": {
-    "@modern-js/builder-doc": "0.0.0-nightly-20240819170736"
+    "@modern-js/builder-doc": "0.0.0-nightly-20240821170648"
   },
   "devDependencies": {
     "@rspress/shared": "1.27.0",
@@ -39,7 +39,7 @@
     "rspress": "1.27.0",
     "ts-node": "^10.9.1",
     "typescript": "^5",
-    "@modern-js/builder-doc": "0.0.0-nightly-20240819170736"
+    "@modern-js/builder-doc": "0.0.0-nightly-20240821170648"
   },
   "scripts": {
     "dev": "rspress dev",