@modern-js/main-doc 2.59.0 → 2.60.1-alpha.0

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

@@ -4,6 +4,51 @@ title: pug
 
 # tools.pug
 
-import Main from '@modern-js/builder-doc/docs/zh/config/tools/pug.md';
+- **类型：** `true | Object | Function | undefined`
+- **默认值：** `false`
 
-<Main />
+配置 [Pug](https://pugjs.org/) 模板引擎。
+
+### Boolean 类型
+
+Modern.js 默认不启用 Pug 模板引擎，你可以将 `tools.pug` 设置为 `true` 来启用它。
+
+```ts
+export default {
+  tools: {
+    pug: true,
+  },
+};
+```
+
+启用后，你可以在 `html.template` 中指定使用 `index.pug` 作为模板文件。
+
+### Object 类型
+
+当 `tools.terser` 的值为 `Object` 类型时，可以配置 Pug 模板引擎的选项：
+
+```ts
+export default {
+  tools: {
+    pug: {
+      doctype: 'xml',
+    },
+  },
+};
+```
+
+详细参数请查看 [Pug API Reference](https://pugjs.org/api/reference.html#options)。
+
+### Function 类型
+
+当 `tools.pug` 配置为 `Function` 类型时，默认配置作为第一个参数传入，可以直接修改配置对象，也可以返回一个值作为最终结果。
+
+```ts
+export default {
+  tools: {
+    pug(config) {
+      config.doctype = 'xml';
+    },
+  },
+};
+```

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 />
 
@@ -77,4 +108,4 @@ export default defineConfig({
 });
 ```
 
-完整配置项请参考 [SWC 插件配置](/guides/rsbuild-plugins/plugin-swc.html#配置)。
+完整配置项请参考 [SWC 插件配置](/plugin/cli-plugins/plugin-swc.html#配置)。

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) 代替，两者功能完全一致。