@modern-js/main-doc 2.60.0 → 2.60.1

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

@@ -1,9 +1,15 @@
 ---
 title: rspack
+configName: tools.rspack
 ---
 
 # tools.rspack
 
-import Main from '@modern-js/builder-doc/docs/zh/config/tools/rspack.md';
+- **类型：** `Rspack.Configuration | Function | undefined`
+- **默认值：** `undefined`
 
-<Main />
+`tools.rspack` 选项用于修改 [Rspack](https://rspack.dev/) 的配置项。
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

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

@@ -4,6 +4,77 @@ title: sass
 
 # tools.sass
 
-import Main from '@modern-js/builder-doc/docs/zh/config/tools/sass.md';
+- **类型：** `Object | Function`
+- **默认值：**
 
-<Main />
+```js
+const defaultOptions = {
+  // 默认在开发环境下启用 CSS 的 Source Map
+  sourceMap: isDev,
+};
+```
+
+你可以通过 `tools.sass` 修改 [sass-loader](https://github.com/webpack-contrib/sass-loader) 的配置。
+
+### Object 类型
+
+当 `tools.sass` 的值为 `Object` 类型时，会与默认配置通过 Object.assign 进行浅层合并，值得注意的是，`sassOptions` 会通过 deepMerge 进行深层合并。
+
+```js
+export default {
+  tools: {
+    sass: {
+      sourceMap: true,
+    },
+  },
+};
+```
+
+### Function 类型
+
+当 `tools.sass` 为 Function 类型时，默认配置作为第一个参数传入，可以直接修改配置对象，也可以返回一个值作为最终结果，第二个参数提供了一些可以直接调用的工具函数：
+
+```js
+export default {
+  tools: {
+    sass(config) {
+      // 修改 sourceMap 配置
+      config.additionalData = async (content, loaderContext) => {
+        // ...
+      };
+    },
+  },
+};
+```
+
+### 修改 Sass 版本
+
+在某些场景下，如果你需要使用特定的 Sass 版本，而不是使用 Modern.js 内置的 Dart Sass v1，可以在项目中安装需要使用的 Sass 版本，并通过 `sass-loader` 的 `implementation` 选项设置。
+
+```js
+export default {
+  tools: {
+    sass: {
+      implementation: require('sass'),
+    },
+  },
+};
+```
+
+### 工具函数
+
+#### addExcludes
+
+- **类型：** `(excludes: RegExp | RegExp[]) => void`
+
+用来指定 `sass-loader` 不编译哪些文件，你可以传入一个或多个正则表达式来匹配 sass 文件的路径。例如：
+
+```js
+export default {
+  tools: {
+    sass(config, { addExcludes }) {
+      addExcludes(/node_modules/);
+    },
+  },
+};
+```

package/docs/zh/configure/app/tools/style-loader.mdx

@@ -1,9 +1,15 @@
 ---
 title: styleLoader
+configName: tools.styleLoader
 ---
 
 # tools.styleLoader
 
-import Main from '@modern-js/builder-doc/docs/zh/config/tools/styleLoader.md';
+- **类型：** `Object | Function`
+- **默认值：** `{}`
 
-<Main />
+通过 `tools.styleLoader` 可以设置 [style-loader](https://github.com/webpack-contrib/style-loader) 的配置项。
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/zh/configure/app/tools/styled-components.mdx

@@ -4,6 +4,51 @@ title: styledComponents
 
 # tools.styledComponents
 
-import Main from '@modern-js/builder-doc/docs/zh/config/tools/styledComponents.md';
+- **类型：** `Object | Function | false`
+- **默认值：**
 
-<Main />
+```js
+{
+  displayName: true,
+  // 在 SSR 构建中 isSSR 为 true
+  ssr: isSSR,
+  // 在生产环境构建时启用 `pure` 来优化包体积
+  pure: isProd,
+  transpileTemplateLiterals: true,
+}
+```
+
+对应 [babel-plugin-styled-components](https://github.com/styled-components/babel-plugin-styled-components) 或使用 SWC 时 [@swc/plugin-styled-components](https://github.com/swc-project/plugins/tree/main/packages/styled-components) 的配置。 值为 `Object` 类型时，利用 Object.assign 函数与默认配置合并。比如:
+
+```js
+export default {
+  tools: {
+    styledComponents: {
+      pure: false,
+    },
+  },
+};
+```
+
+值为 `Function` 类型时，第一个参数为默认配置，第二个参数提供了一些可以直接调用的工具函数：
+
+```js
+export default {
+  tools: {
+    styledComponents(config) {
+      // 修改 pure 配置
+      config.pure = false;
+    },
+  },
+};
+```
+
+该特性默认启用，你可以配置 `tools.styledComponents` 为 `false` 来关闭该行为，关闭后可以提升编译性能：
+
+```js
+export default {
+  tools: {
+    styledComponents: false,
+  },
+};
+```

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

@@ -9,7 +9,7 @@ title: swc
 
 ## 介绍
 
-import SWC from '@modern-js/builder-doc/docs/zh/shared/swc.md';
+import SWC from '@site-docs/components/swc.mdx';
 
 <SWC />
 
@@ -37,9 +37,40 @@ export default defineConfig<'rspack'>({
 
 更多用法可参考 [Rsbuild - tools.swc](https://rsbuild.dev/zh/config/tools/swc)。
 
+### 注册 SWC 插件
+
+Modern.js 支持通过 `tools.swc` 注册 SWC 的 Wasm 插件，比如注册 [@swc/plugin-styled-components](https://www.npmjs.com/package/@swc/plugin-styled-components)：
+
+```ts
+export default {
+  tools: {
+    swc: {
+      jsc: {
+        experimental: {
+          plugins: [['@swc/plugin-styled-components', {}]],
+        },
+      },
+    },
+  },
+};
+```
+
+需要注意的是，SWC 的插件仍然是一个实验性功能，目前 SWC 的 Wasm 插件是不向后兼容的，SWC 插件的版本与 Rspack 依赖的 swc_core 版本存在强耦合关系。
+
+这意味着，你需要选择和当前 swc_core 版本匹配的 SWC 插件，才能使它正常执行。如果你使用的 SWC 插件版本与 Rspack 依赖的 swc_core 版本不匹配，Rspack 在执行构建时会抛出如下错误：
+
+```
+1: failed to run Wasm plugin transform. Please ensure the version of `swc_core`
+   used by the plugin is compatible with the host runtime.
+```
+
+如果你遇到了以上问题，通常可行的解决方法是将 Modern.js 和 SWC 插件都升级到最新版本。
+
+详情可参考 [Rsbuild - SWC 插件版本](https://rsbuild.dev/zh/guide/basic/configure-swc#swc-%E6%8F%92%E4%BB%B6%E7%89%88%E6%9C%AC)。
+
 ## 在 Webpack 模式下使用
 
-import EnableSWC from '@modern-js/builder-doc/docs/zh/shared/enableSwc.md';
+import EnableSWC from '@site-docs/components/enableSwc.mdx';
 
 <EnableSWC />
 

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

@@ -4,6 +4,53 @@ title: terser
 
 # tools.terser
 
-import Main from '@modern-js/builder-doc/docs/zh/config/tools/terser.md';
+- **类型：** `Object | Function | undefined`
+- **默认值：**
 
-<Main />
+```js
+const defaultTerserOptions = {
+  terserOptions: {
+    mangle: {
+      safari10: true,
+    },
+  },
+};
+```
+
+- **打包工具：** `仅支持 webpack`
+
+在生产环境构建时，Modern.js 会通过 [terser-webpack-plugin](https://github.com/webpack-contrib/terser-webpack-plugin) 对 JavaScript 代码进行压缩优化。可以通过 `tools.terser` 修改 [terser-webpack-plugin](https://github.com/webpack-contrib/terser-webpack-plugin) 的配置。
+
+### Object 类型
+
+当 `tools.terser` 的值为 `Object` 类型时，会与默认配置通过 `Object.assign` 合并。
+
+例如通过 `exclude` 排除部分文件的压缩：
+
+```js
+export default {
+  tools: {
+    terser: {
+      exclude: /\/excludes/,
+    },
+  },
+};
+```
+
+### Function 类型
+
+当 `tools.terser` 配置为 `Function` 类型时，默认配置作为第一个参数传入，可以直接修改配置对象，也可以返回一个值作为最终结果。
+
+```js
+export default {
+  tools: {
+    terser: opts => {
+      opts.exclude = /\/excludes/;
+    },
+  },
+};
+```
+
+:::tip 禁用代码压缩
+如果你需要禁用代码压缩，可以使用 [output.disableMinimize](https://modernjs.dev/builder/api/config-output.html#outputdisableminimize) 配置项。
+:::

package/docs/zh/configure/app/tools/ts-checker.mdx

@@ -4,6 +4,53 @@ title: tsChecker
 
 # tools.tsChecker
 
-import Main from '@modern-js/builder-doc/docs/zh/config/tools/tsChecker.md';
+- **类型：** `Object | Function`
+- **默认值：**
 
-<Main />
+```js
+const defaultOptions = {
+  typescript: {
+    // avoid OOM issue
+    memoryLimit: 8192,
+    // use tsconfig of user project
+    configFile: tsconfigPath,
+    // use typescript of user project
+    typescriptPath: require.resolve('typescript'),
+  },
+  issue: {
+    exclude: [
+      { file: '**/*.(spec|test).ts' },
+      { file: '**/node_modules/**/*' },
+    ],
+  },
+  logger: {
+    log() {
+      // do nothing
+      // we only want to display error messages
+    },
+    error(message: string) {
+      console.error(message.replace(/ERROR/g, 'Type Error'));
+    },
+  },
+},
+```
+
+默认情况下，Modern.js 会开启 [@rsbuild/plugin-type-check](https://rsbuild.dev/zh/plugins/list/plugin-type-check) 进行类型检查。你可以通过 `output.disableTsChecker` 配置项来关闭类型检查。
+
+## 示例
+
+当 `tsChecker` 的值为 Object 类型时，会与默认配置进行深层合并。
+
+```ts
+export default {
+  tools: {
+    tsChecker: {
+      issue: {
+        exclude: [({ file = '' }) => /[\\/]some-folder[\\/]/.test(file)],
+      },
+    },
+  },
+};
+```
+
+> 请参考 [@rsbuild/plugin-type-check](https://rsbuild.dev/zh/plugins/list/plugin-type-check) 了解更多用法。

package/docs/zh/configure/app/tools/ts-loader.mdx

@@ -4,6 +4,67 @@ title: tsLoader
 
 # tools.tsLoader
 
-import Main from '@modern-js/builder-doc/docs/zh/config/tools/tsLoader.md';
+- **类型：** `Object | Function | undefined`
+- **默认值：** `undefined`
+- **打包工具：** `仅支持 webpack`
 
-<Main />
+:::warning 不再推荐使用 ts-loader
+使用 [babel-loader](https://modernjs.dev/builder/guide/basic/typescript.html#%E4%B8%BA%E4%BB%80%E4%B9%88%E9%BB%98%E8%AE%A4%E4%BD%BF%E7%94%A8-babel) 或 [Rspack](https://modernjs.dev/guide/advanced/rspack-start.html) 转译 TypeScript 代码的性能明显优于 ts-loader 且能够使用更多拓展能力。
+
+启用 ts-loader 时将无法使用 [source.transformImport](https://modernjs.dev/configure/app/source/transform-import.html) 和 [tools.styledComponents](https://modernjs.dev/configure/app/tools/styled-components.html) 等由 Babel 和 SWC 提供支持的能力。
+:::
+
+项目中默认不开启 ts-loader，当 `tools.tsLoader` 不为 undefined 则表示开启 ts-loader，同时禁用 babel-loader 对 TypeScript 的编译。
+
+### Object 类型
+
+当此值为 Object 类型时，与默认配置通过 Object.assign 合并。
+
+默认配置如下:
+
+```json
+{
+  "compilerOptions": {
+    "target": "es5",
+    "module": "ESNext"
+  },
+  "transpileOnly": true,
+  "allowTsInNodeModules": true
+}
+```
+
+你可以通过 `tools.tsLoader` 配置项来覆盖默认配置:
+
+```ts
+export default {
+  tools: {
+    tsLoader: {
+      allowTsInNodeModules: false,
+    },
+  },
+};
+```
+
+### Function 类型
+
+当此值为 Function 类型时，默认配置作为第一参数传入，可以直接修改配置对象，也可以返回一个对象作为最终配置；第二个参数为修改 `ts-loader` 配置工具函数集合：
+
+```ts
+export default {
+  tools: {
+    tsLoader: opts => {
+      opts.allowTsInNodeModules = false;
+    },
+  },
+};
+```
+
+### 工具函数
+
+#### addIncludes
+
+已废弃，请使用 [source.include](https://modernjs.dev/configure/app/source/include.html) 代替，两者功能完全一致。
+
+#### addExcludes
+
+已废弃，请使用 [source.exclude](https://modernjs.dev/configure/app/source/exclude.html) 代替，两者功能完全一致。

package/docs/zh/configure/app/tools/webpack-chain.mdx

@@ -4,6 +4,247 @@ title: webpackChain
 
 # tools.webpackChain
 
-import Main from '@modern-js/builder-doc/docs/zh/config/tools/webpackChain.md';
+- **类型：** `Function | undefined`
+- **默认值：** `undefined`
+- **打包工具：** `仅支持 webpack`
 
-<Main />
+你可以通过 `tools.webpackChain` 来修改默认的 webpack 配置，它的值为 `Function` 类型，接收两个参数：
+
+- 第一个参数为 `webpack-chain` 对象实例，你可以通过这个实例来修改默认的 webpack 配置。
+- 第二个参数为一个工具集合，包括`env`、`isProd`、`CHAIN_ID` 等。
+
+相比于 `tools.webpack`，**webpack-chain 不仅支持链式调用，而且能够基于别名来定位到内置的 Rule 或 Plugin，从而实现精准的配置修改**。我们推荐使用 `tools.webpackChain` 来代替 `tools.webpack`。
+
+> `tools.webpackChain` 的执行时机早于 tools.webpack，因此会被 `tools.webpack` 中的修改所覆盖。
+
+### 工具集合
+
+#### env
+
+- **类型：** `'development' | 'production' | 'test'`
+
+通过 env 参数可以判断当前环境为 development、production 还是 test。比如：
+
+```js
+export default {
+  tools: {
+    webpackChain: (chain, { env }) => {
+      if (env === 'development') {
+        chain.devtool('cheap-module-eval-source-map');
+      }
+    },
+  },
+};
+```
+
+#### isProd
+
+- **类型：** `boolean`
+
+通过 isProd 参数可以判断当前环境是否为 production。比如：
+
+```js
+export default {
+  tools: {
+    webpackChain: (chain, { isProd }) => {
+      if (isProd) {
+        chain.devtool('source-map');
+      }
+    },
+  },
+};
+```
+
+#### target
+
+- **类型：** `'web' | 'node' | 'modern-web' | 'web-worker'`
+
+通过 target 参数可以判断当前构建的目标运行时环境。比如：
+
+```js
+export default {
+  tools: {
+    webpackChain: (chain, { target }) => {
+      if (target === 'node') {
+        // ...
+      }
+    },
+  },
+};
+```
+
+#### isServer
+
+- **类型：** `boolean`
+
+判断当前构建的目标运行时环境是否为 `node`，等价于 `target === 'node'`。
+
+```js
+export default {
+  tools: {
+    webpackChain: (chain, { isServer }) => {
+      if (isServer) {
+        // ...
+      }
+    },
+  },
+};
+```
+
+#### isWebWorker
+
+- **类型：** `boolean`
+
+判断当前构建的目标运行时环境是否为 `web-worker`，等价于 `target === 'web-worker'`。
+
+```js
+export default {
+  tools: {
+    webpackChain: (chain, { isWebWorker }) => {
+      if (isWebWorker) {
+        // ...
+      }
+    },
+  },
+};
+```
+
+#### webpack
+
+- **类型：** `typeof import('webpack')`
+
+通过这个参数你可以拿到 webpack 实例。比如：
+
+```js
+export default {
+  tools: {
+    webpackChain: (chain, { webpack }) => {
+      chain.plugin('my-progress').use(webpack.ProgressPlugin);
+    },
+  },
+};
+```
+
+#### HtmlWebpackPlugin
+
+- **类型：** `typeof import('html-webpack-plugin')`
+
+通过这个参数你可以拿到 HtmlWebpackPlugin 实例。
+
+```js
+export default {
+  tools: {
+    webpackChain: (chain, { HtmlWebpackPlugin }) => {
+      console.log(HtmlWebpackPlugin);
+    },
+  },
+};
+```
+
+#### CHAIN_ID
+
+Modern.js 中预先定义了一些常用的 Chain ID，你可以通过这些 ID 来定位到内置的 Rule 或 Plugin。
+
+:::tip
+请留意，下列的一部分 Rule 或 Plugin 并不是默认存在的，当你开启特定配置项、或是注册某些插件后，它们才会被包含在 webpack 配置中。
+
+比如，`RULE.STYLUS` 仅在注册了 Stylus 插件后才会存在。
+:::
+
+#### CHAIN_ID.RULE
+
+| ID            | 描述                                                                                          |
+| ------------- | --------------------------------------------------------------------------------------------- |
+| `RULE.MJS`    | 处理 `mjs` 的规则                                                                             |
+| `RULE.JS`     | 处理 `js` 的规则                                                                              |
+| `RULE.TS`     | 处理 `ts` 的规则                                                                              |
+| `RULE.CSS`    | 处理 `css` 的规则                                                                             |
+| `RULE.LESS`   | 处理 `less` 的规则                                                                            |
+| `RULE.SASS`   | 处理 `sass` 的规则                                                                            |
+| `RULE.STYLUS` | 处理 `stylus` 的规则（依赖 [Stylus 插件](https://rsbuild.dev/zh/plugins/list/plugin-stylus)） |
+| `RULE.SVG`    | Rule for `svg`                                                                                |
+| `RULE.PUG`    | 处理 `pug` 的规则                                                                             |
+| `RULE.TOML`   | 处理 `toml` 的规则                                                                            |
+| `RULE.YAML`   | 处理 `yaml` 的规则                                                                            |
+| `RULE.WASM`   | 处理 `wasm` 的规则                                                                            |
+| `RULE.NODE`   | 处理 `node` 的规则                                                                            |
+| `RULE.FONT`   | 处理字体的规则                                                                                |
+| `RULE.IMAGE`  | 处理图片的规则                                                                                |
+| `RULE.MEDIA`  | 处理媒体资源的规则                                                                            |
+
+#### CHAIN_ID.ONE_OF
+
+通过 `ONE_OF.XXX` 可以匹配到规则数组中的某一类规则。
+
+| ID                  | 描述                                                |
+| ------------------- | --------------------------------------------------- |
+| `ONE_OF.SVG`        | 处理 SVG 的规则，在 data URI 和单独文件之间自动选择 |
+| `ONE_OF.SVG_URL`    | 处理 SVG 的规则，输出为单独文件                     |
+| `ONE_OF.SVG_INLINE` | 处理 SVG 的规则，作为 data URI 内联到 bundle 中     |
+| `ONE_OF.SVG_ASSETS` | 处理 SVG 的规则，在 data URI 和单独文件之间自动选择 |
+
+#### CHAIN_ID.USE
+
+通过 `USE.XXX` 可以匹配到对应的 loader。
+
+| ID                                | 描述                                  |
+| --------------------------------- | ------------------------------------- |
+| `USE.TS`                          | 对应 `ts-loader`                      |
+| `USE.CSS`                         | 对应 `css-loader`                     |
+| `USE.LESS`                        | 对应 `less-loader`                    |
+| `USE.SASS`                        | 对应 `sass-loader`                    |
+| `USE.STYLUS`                      | 对应 `stylus-loader`                  |
+| `USE.PUG`                         | 对应 `pug-loader`                     |
+| `USE.VUE`                         | 对应 `vue-loader`                     |
+| `USE.TOML`                        | 对应 `toml-loader`                    |
+| `USE.YAML`                        | 对应 `yaml-loader`                    |
+| `USE.NODE`                        | 对应 `node-loader`                    |
+| `USE.URL`                         | 对应 `url-loader`                     |
+| `USE.SVGR`                        | 对应 `@svgr/webpack`                  |
+| `USE.BABEL`                       | 对应 `babel-loader`                   |
+| `USE.STYLE`                       | 对应 `style-loader`                   |
+| `USE.POSTCSS`                     | 对应 `postcss-loader`                 |
+| `USE.CSS_MODULES_TS`              | 对应 `css-modules-typescript-loader`  |
+| `USE.MINI_CSS_EXTRACT`            | 对应 `mini-css-extract-plugin.loader` |
+| `USE.RESOLVE_URL_LOADER_FOR_SASS` | 对应 `resolve-url-loader`             |
+
+#### CHAIN_ID.PLUGIN
+
+通过 `PLUGIN.XXX` 可以匹配到对应的 plugin。
+
+| ID                             | 描述                                                                               |
+| ------------------------------ | ---------------------------------------------------------------------------------- |
+| `PLUGIN.HMR`                   | 对应 `HotModuleReplacementPlugin`                                                  |
+| `PLUGIN.COPY`                  | 对应 `CopyWebpackPlugin`                                                           |
+| `PLUGIN.HTML`                  | 对应 `HtmlWebpackPlugin`，使用时需要拼接 entry 名称：`${PLUGIN.HTML}-${entryName}` |
+| `PLUGIN.DEFINE`                | 对应 `DefinePlugin`                                                                |
+| `PLUGIN.IGNORE`                | 对应 `IgnorePlugin`                                                                |
+| `PLUGIN.BANNER`                | 对应 `BannerPlugin`                                                                |
+| `PLUGIN.PROGRESS`              | 对应 `Webpackbar`                                                                  |
+| `PLUGIN.APP_ICON`              | 对应 `AppIconPlugin`                                                               |
+| `PLUGIN.MANIFEST`              | 对应 `WebpackManifestPlugin`                                                       |
+| `PLUGIN.TS_CHECKER`            | 对应 `ForkTsCheckerWebpackPlugin`                                                  |
+| `PLUGIN.INLINE_HTML`           | 对应 `InlineChunkHtmlPlugin`                                                       |
+| `PLUGIN.BUNDLE_ANALYZER`       | 对应 `WebpackBundleAnalyzer`                                                       |
+| `PLUGIN.MINI_CSS_EXTRACT`      | 对应 `MiniCssExtractPlugin`                                                        |
+| `PLUGIN.VUE_LOADER_PLUGIN`     | 对应 `VueLoaderPlugin`                                                             |
+| `PLUGIN.REACT_FAST_REFRESH`    | 对应 `ReactFastRefreshPlugin`                                                      |
+| `PLUGIN.NODE_POLYFILL_PROVIDE` | 对应处理 node polyfill 的 `ProvidePlugin`                                          |
+| `PLUGIN.SUBRESOURCE_INTEGRITY` | 对应 `webpack-subresource-integrity`                                               |
+| `PLUGIN.ASSETS_RETRY`          | 对应 webpack 静态资源重试插件 `WebpackAssetsRetryPlugin`              |
+| `PLUGIN.AUTO_SET_ROOT_SIZE`    | 对应自动设置根字体大小插件 `AutoSetRootSizePlugin`                    |
+
+#### CHAIN_ID.MINIMIZER
+
+通过 `MINIMIZER.XXX` 可以匹配到对应的压缩工具。
+
+| ID                  | 描述                             |
+| ------------------- | -------------------------------- |
+| `MINIMIZER.JS`      | 对应 `TerserWebpackPlugin`       |
+| `MINIMIZER.CSS`     | 对应 `CssMinimizerWebpackPlugin` |
+| `MINIMIZER.ESBUILD` | 对应 `ESBuildPlugin`             |
+| `MINIMIZER.SWC`     | 对应 `SwcWebpackPlugin`          |
+
+### 使用示例
+
+使用示例可参考：[WebpackChain 使用示例](https://modernjs.dev/builder/guide/advanced/custom-webpack-config.html#%E4%BD%BF%E7%94%A8-webpack-chain)。