@modern-js/module-tools-docs 2.24.1 → 2.25.1

package/docs/zh/api/config/build-config.md

@@ -2,9 +2,20 @@
 sidebar_position: 1
 ---
 
-# BuildConfig
+# buildConfig
 
-本章节描述了 Module Tools 关于构建的所有配置
+`buildConfig` 是一个用来描述如何编译、生成构建产物的配置项，它包含了构建的所有配置。
+
+- 类型：`object | object[]`
+- 默认值: `undefined`
+
+:::tip
+在开始使用 `buildConfig` 之前，请先阅读以下文档来了解其作用：
+
+- [修改输出产物](/guide/basic/modify-output-product.html)
+- [深入理解构建](/guide/advance/in-depth-about-build.html)
+
+:::
 
 ## alias
 
@@ -110,7 +121,7 @@ export default defineConfig({
 
 打包时将 SVG 作为一个 React 组件处理，options 参考 [svgr](https://react-svgr.com/docs/options/)，另外还支持了 `include` 和 `exclude` 两个配置项，用于匹配需要处理的 SVG 文件。
 
-- 类型： `boolean | Object`
+- 类型： `boolean | object`
 - 默认值： `false`
 
 开启 svgr 功能后，可以使用默认导出的方式将 SVG 当做组件使用。
@@ -161,7 +172,7 @@ declare module '*.svg' {
 
 自动外置项目的 `"dependencies"` 和 `"peerDependencies"`，不会将其打包到最终的 bundle 产物中。
 
-- 类型： `boolean | Object`
+- 类型： `boolean | object`
 - 默认值： `true`
 
 当我们希望关闭对于第三方依赖的默认处理行为时候，可以通过以下方式来实现：
@@ -213,7 +224,7 @@ export default defineConfig({
 
 将文件或目录拷贝到指定位置。
 
-- 类型： `Object`
+- 类型： `object`
 
 ```js modern.config.ts
 export default defineConfig({
@@ -295,7 +306,7 @@ export default defineConfig({
 
 类型文件生成的相关配置，默认情况会生成。
 
-- 类型： `false | Object`
+- 类型： `false | object`
 - 默认值：
 
 ```js
@@ -435,24 +446,107 @@ export var yourCode = function () {
 
 ## externals
 
-配置外部依赖，不会被打包到最终的 bundle 中。
+用于在打包时排除一些外部依赖，避免将这些依赖打包到最终的 bundle 中。
+
+- 类型：
+
+```ts
+type Externals = (string | RegExp)[];
+```
 
-- 类型： `(string | RegExp)[]`
 - 默认值： `[]`
+- 构建类型：`仅支持 buildType: 'bundle'`
+- 示例：
+
+```js modern.config.ts
+export default defineConfig({
+  buildConfig: {
+    // 避免打包 React
+    externals: ['react'],
+  },
+});
+```
 
 ## format
 
-js 产物输出的格式,其中 `iife` 和 `umd` 只能在 `buildType` 为 `bundle` 时生效。
+用于设置 JavaScript 产物输出的格式，其中 `iife` 和 `umd` 只在 `buildType` 为 `bundle` 时生效。
+
+- 类型：`'esm' | 'cjs' | 'iife' | 'umd'`
+- 默认值：`cjs`
+
+### format: 'esm'
+
+esm 代表 "ECMAScript 模块"，它需要运行环境支持 import 和 export 语法。
 
-- 类型： `'esm' | 'cjs' | 'iife' | 'umd'`
-- 默认值： `cjs`
+- 示例：
+
+```js modern.config.ts
+export default defineConfig({
+  buildConfig: {
+    format: 'esm',
+  },
+});
+```
+
+### format: 'cjs'
+
+cjs 代表 "CommonJS"，它需要运行环境支持 exports、require 和 module 语法，通常为 Node.js 环境。
+
+- 示例：
+
+```js modern.config.ts
+export default defineConfig({
+  buildConfig: {
+    format: 'cjs',
+  },
+});
+```
+
+### format: 'iife'
+
+iife 代表 "立即调用函数表达式"，它将代码包裹在函数表达式中，确保代码中的任何变量不会意外地与全局范围中的变量冲突，通常在浏览器环境中运行。
+
+- 示例：
+
+```js modern.config.ts
+export default defineConfig({
+  buildConfig: {
+    format: 'iife',
+  },
+});
+```
+
+### format: 'umd'
+
+umd 代表 "Universal Module Definition"，用于在不同环境（浏览器、Node.js 等）中运行。umd 格式的模块可以在多种环境下使用，既可以作为全局变量访问，也可以通过模块加载器（如 RequireJS）进行模块化加载。
+
+- 示例：
+
+```js modern.config.ts
+export default defineConfig({
+  buildConfig: {
+    format: 'umd',
+  },
+});
+```
 
 ## input
 
 指定构建的入口文件，数组形式可以指定目录。
 
-- 类型： `string[] | Record<string, string>`
-- 默认值： `bundle` 模式下默认为 `['src/index.ts']`，`bundleless` 模式下默认为 `['src']`
+- 类型：
+
+```ts
+type Input =
+  | string[];
+  | {
+      [name: string]: string;
+    }
+```
+
+- 默认值：`bundle` 模式下默认为 `['src/index.ts']`，`bundleless` 模式下默认为 `['src']`
+
+**数组用法：**
 
 ```js modern.config.ts
 export default defineConfig({
@@ -462,25 +556,74 @@ export default defineConfig({
 });
 ```
 
+**对象用法：**
+
+当在 bundle 模式下需要修改产物的输出文件名称的时候，可以使用对象形式进行配置。
+
+**对象的 Key 是产物的文件名称，Value 是源码的文件路径。**
+
+```js modern.config.ts
+export default defineConfig({
+  buildConfig: {
+    format: 'esm',
+    input: {
+      'index.esm': './src/index.ts',
+    },
+  },
+});
+```
+
 ## jsx
 
-指定 jsx 的编译方式, 默认支持 React17 以上,自动注入 jsx 运行时代码。
+指定 JSX 的编译方式，默认支持 React 17 及更高版本，自动注入 JSX 运行时代码。
 
-- 类型： `automatic | classic`
+- 类型： `automatic | transform`
 - 默认值： `automatic`
 
+如果你需要支持 React 16，则可以设置 `jsx` 为 `transform`：
+
+```js modern.config.ts
+export default defineConfig({
+  buildConfig: {
+    jsx: 'transform',
+  },
+});
+```
+
+:::tip
+关于 JSX Transform 的更多说明，可以参考以下链接：
+
+- [React Blog - Introducing the New JSX Transform](https://legacy.reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html).
+- [esbuild - JSX](https://esbuild.github.io/api/#jsx).
+
+:::
+
 ## metafile
 
-esbuild 以 JSON 格式生成有关构建的一些元数据，可以通过例如 [bundle-buddy](https://bundle-buddy.com/esbuild) 的工具可视化
+这个选项用于构建分析，开启该选项后，esbuild 会以 JSON 格式生成有关构建的一些元数据。
 
 - 类型：`boolean`
 - 默认值：`false`
+- 构建类型：`仅支持 buildType: 'bundle'`
+
+开启 `metafile` 生成：
+
+```js modern.config.ts
+export default defineConfig({
+  buildConfig: {
+    buildType: 'bundle',
+    metafile: true,
+  },
+});
+```
+
+在执行 build 构建后，产物目录下会生成 `metafile-[xxx].json` 文件，你可以通过 [esbuild analyze](https://esbuild.github.io/analyze/) 和 [bundle-buddy](https://bundle-buddy.com/esbuild) 等工具进行可视化分析。
 
 ## minify
 
 使用 esbuild 或者 terser 压缩代码，也可以传入 [terserOptions](https://github.com/terser/terser#minify-options)。
 
-- 类型： `'terser' | 'esbuild' | false | Object`
+- 类型： `'terser' | 'esbuild' | false | object`
 - 默认值： `false`
 
 ```js modern.config.ts
@@ -592,8 +735,8 @@ export default defineConfig({
 
 设置源码的格式。默认情况下，会将源码作为 EsModule 进行处理。当源码使用的是 CommonJS 的时候，需要设置 `commonjs`。
 
-- 类型：`commonjs` | `module`
-- 默认值：`module`
+- 类型：`'commonjs' | 'module'`
+- 默认值：`'module'`
 
 ## splitting
 
@@ -614,7 +757,7 @@ less 相关配置。
 
 详细配置参考 [less](https://less.bootcss.com/usage/#less-options)。
 
-- 类型： `Object`
+- 类型： `object`
 - 默认值： `{ javascriptEnabled: true }`
 
 ## style.less.additionalData
@@ -640,10 +783,10 @@ export default defineConfig({
 
 配置 `Less` 使用的实现库，在不指定的情况下，使用的内置版本是 `4.1.3`。
 
-- 类型： `string | Object`
+- 类型： `string | object`
 - 默认值： `undefined`
 
-`Object` 类型时，指定 `Less` 的实现库
+设置 `object` 类型时，可以指定 `Less` 的实现库。
 
 ```js modern.config.ts
 export default defineConfig({
@@ -679,7 +822,7 @@ Sass 相关配置。
 
 详细配置参考 [node-sass](https://github.com/sass/node-sass#options)
 
-- 类型： `Object`
+- 类型： `object`
 - 默认值： `{}`
 
 ## style.sass.additionalData
@@ -706,10 +849,10 @@ export default defineConfig({
 
 配置 `Sass` 使用的实现库，在不指定的情况下，使用的内置版本是 `1.5.4`。
 
-- 类型： `string | Object`
+- 类型： `string | object`
 - 默认值： `undefined`
 
-`Object` 类型时，指定 `Sass` 的实现库
+设置为 `object` 类型时，可以指定 `Sass` 的实现库。
 
 ```js modern.config.ts
 export default defineConfig({
@@ -744,6 +887,20 @@ export default defineConfig({
 
 详细配置查看 [PostCSS](https://github.com/postcss/postcss#options)。
 
+**基础使用：**
+
+```js modern.config.ts
+export default defineConfig({
+  buildConfig: {
+    style: {
+      postcss: {
+        plugins: [yourPostCSSPlugin],
+      },
+    },
+  },
+});
+```
+
 ## style.inject
 
 配置打包模式下是否将 CSS 样式插入到 JavaScript 代码中。
@@ -807,9 +964,9 @@ style_inject_es_default(css_248z);
 
 ## style.modules
 
-CSS Modules 配置
+CSS Modules 配置。
 
-- 类型： `Object`
+- 类型： `object`
 - 默认值： `{}`
 
 一个常用的配置是 `localsConvention`，它可以改变 CSS Modules 的类名生成规则。
@@ -834,7 +991,7 @@ export default defineConfig({
 }
 ```
 
-你可以使用 `styles.boxTitle` 来访问
+你可以使用 `styles.boxTitle` 来访问。
 
 详细配置查看 [postcss-modules](https://github.com/madyankin/postcss-modules#usage)
 
@@ -842,7 +999,7 @@ export default defineConfig({
 
 Tailwind CSS 相关配置。
 
-- 类型： `Object | Function`
+- 类型： `object | Function`
 - 默认值： `见下方配置详情`
 
 <details>
@@ -863,7 +1020,7 @@ const tailwind = {
 };
 ```
 
-值为 `Object` 类型时，与默认配置通过 `Object.assign` 合并。
+值为 `object` 类型时，与默认配置通过 `Object.assign` 合并。
 
 值为 `Function` 类型时，函数返回的对象与默认配置通过 `Object.assign` 合并。
 
@@ -908,7 +1065,7 @@ export default defineConfig({
 
 提供与 babel-plugin-import 等价的能力和配置，基于 SWC 实现。
 
-- 类型：`Array`
+- 类型：`object[]`
 - 默认值：`[]`
 
 数组元素为一个 babel-plugin-import 的配置对象。配置对象可以参考 [options](https://github.com/umijs/babel-plugin-import#options)。
@@ -931,7 +1088,7 @@ export default defineConfig({
 
 ### 注意事项
 
-参考[【Import 插件——注意事项】](plugins/official-list/plugin-import.html#注意事项)
+参考[「Import 插件——注意事项」](plugins/official-list/plugin-import.html#注意事项)
 
 ## umdGlobals
 
@@ -957,7 +1114,7 @@ export default defineConfig({
 
 指定 UMD 产物的模块名。
 
-- 类型： `string` | `Function`
+- 类型： `string | Function`
 - 默认值： `name => name`
 
 ```js modern.config.ts

package/docs/zh/api/config/build-preset.mdx

@@ -2,7 +2,7 @@
 sidebar_position: 2
 ---
 
-# BuildPreset
+# buildPreset
 
 构建的预设字符串或者预设函数。提供开箱即用的构建配置。
 

package/docs/zh/api/config/design-system.md

@@ -2,15 +2,15 @@
 sidebar_position: 3
 ---
 
-# DesignSystem
+# designSystem
 
-本章描述了有关 designSystem 相关的配置
+本章描述了有关 designSystem 相关的配置。
 
 :::tip
 需要先通过 `pnpm run new` 启用 Tailwind CSS 功能。
 :::
 
-- 类型：`Object`
+- 类型：`object`
 - 默认值: `见下方配置详情`。
 
 <details>

package/docs/zh/api/config/dev.md

@@ -2,16 +2,18 @@
 sidebar_position: 3
 ---
 
-# Dev Config
+# dev
 
 本章节描述了 Module Tools 关于调试工具相关的所有配置。
 
-``` ts
+```ts
 export default {
   dev: {
-    storybook: {/* Storybook Config */},
+    storybook: {
+      /* Storybook Config */
+    },
   },
-}
+};
 ```
 
 ## storybook
@@ -21,36 +23,34 @@ export default {
 - 开启 Storybook 调试功能或者安装 `@modern-js/plugin-storybook` 插件。
 - 注册 `@modern-js/plugin-storybook` 插件。
 
-> 关于如何开启 Storybook 调试功能，可以参考：[【Storybook 调试】](guide/basic/use-micro-generator#storybook-调试)
-
-
+> 关于如何开启 Storybook 调试功能，可以参考：[「Storybook 调试」](guide/basic/use-micro-generator#storybook-调试)
 
 ### storybook.webpack
 
-- 类型：`Object` | `Function` | `undefined`
-
+- 类型：`object | Function | undefined`
 - 默认值：`undefined`
 
-``` ts
+```ts
 export default {
   dev: {
     storybook: {
       webpack(config) {
         return config;
       },
-    }
-  }
-}
+    },
+  },
+};
 ```
 
-你可以通过 `dev.storybook.webpack` 来修改 Storybook Preview-iframe 的 webpack 配置。使用方式可以参考 Modern.js Builder 的 [`tools.webpack`](https://modernjs.dev/builder/api/config-tools.html#tools.webpack) 配置。
+你可以通过 `dev.storybook.webpack` 来修改 Storybook Preview-iframe 的 webpack 配置。使用方式可以参考 Modern.js Builder 的 [`tools.webpack`](https://modernjs.dev/builder/api/config-tools.html#toolswebpack) 配置。
 
 ![Storybook](https://storybook.js.org/71522ac365feaf3338d7c242e53378f6/manager-preview.png)
 
-:::tip
-对于 Storybook Manager app 部分的 webpack 配置，可以通过增加 `./config/storybook/main.js` 文件进行配置。
+#### 配置 Manager App
+
+对于 Storybook Manager App 部分的 webpack 配置，可以通过增加 `./config/storybook/main.js` 文件进行配置。
 
-``` js
+```js
 // ./config/storybook/main.js
 
 module.exports = {
@@ -61,25 +61,22 @@ module.exports = {
   },
 };
 ```
-:::
-
 
 ### storybook.webpackChain
 
-- 类型：`Function` | `undefined`
-
+- 类型：`Function | undefined`
 - 默认值：`undefined`
 
-``` ts
+```ts
 export default {
   dev: {
     storybook: {
       webpackChain(chain) {
         return chain;
       },
-    }
-  }
-}
+    },
+  },
+};
 ```
 
-你可以通过 `dev.storybook.webpackChain` 来修改 Storybook Preview-iframe 的 webpack 配置。使用方式可以参考 Modern.js Builder 的 [`tools.webpackChain`](https://modernjs.dev/builder/api/config-tools.html#tools.webpackchain) 配置。
+你可以通过 `dev.storybook.webpackChain` 来修改 Storybook Preview-iframe 的 webpack 配置。使用方式可以参考 Modern.js Builder 的 [`tools.webpackChain`](https://modernjs.dev/builder/api/config-tools.html#toolswebpackchain) 配置。

package/docs/zh/api/config/plugins.md

@@ -2,17 +2,62 @@
 sidebar_position: 4
 ---
 
-# Plugins
+# plugins
 
 本章介绍注册 Module Tools 插件的配置。
 
-- 类型：`Array<ModuleToolsPlugin>`
+- 类型：`ModuleToolsPlugin[]`
+- 默认值：`undefined`
+
+## 插件执行顺序
+
+默认情况下，自定义插件会按照 `plugins` 数组的顺序依次执行，Module Tools 内置插件的执行时机早于自定义插件。
+
+当插件内部使用了控制顺序的相关字段，比如 `pre`、`post` 时，会基于声明的字段对执行顺序进行调整，详见 [插件之间的关系](https://modernjs.dev/guides/topic-detail/framework-plugin/relationship)。
+
+## 开发插件
+
+关于如何编写插件，可以查看[「插件编写指南」](/plugins/guide/getting-started)。
+
+## 示例
+
+### 使用 npm 上的插件
+
+使用 npm 上的插件，需要通过包管理器安装插件，并通过 import 引入。
+
+```js modern.config.ts
+import { myPlugin } from 'my-plugin';
+
+export default defineConfig({
+  plugins: [myPlugin()],
+});
+```
+
+#### 使用本地插件
+
+使用本地代码仓库中的插件，直接通过相对路径 import 引入即可。
 
 ```js modern.config.ts
-import { examplePlugin } from './plugins/example';
+import { myPlugin } from './plugins/myPlugin';
+
 export default defineConfig({
-  plugins: [examplePlugin()],
+  plugins: [myPlugin()],
 });
 ```
 
-关于如何编写插件，可以查看[【插件编写指南】](/plugins/guide/getting-started)。
+### 插件配置项
+
+如果插件提供了一些自定义的配置项，你可以通过插件函数的参数传入配置。
+
+```js modern.config.ts
+import { myPlugin } from 'my-plugin';
+
+export default defineConfig({
+  plugins: [
+    myPlugin({
+      foo: 1,
+      bar: 2,
+    }),
+  ],
+});
+```

package/docs/zh/api/config/testing.md

@@ -2,7 +2,7 @@
 sidebar_position: 5
 ---
 
-# Testing
+# testing
 
 本章描述了测试相关的配置。
 
@@ -12,10 +12,10 @@ sidebar_position: 5
 
 ## jest
 
-- 类型： `Object | Function`
+- 类型： `object | Function`
 - 默认值：`{}`
 
-对应 [Jest](https://jestjs.io/docs/configuration) 的配置，当为 `Object` 类型时，可以配置 Jest 所支持的所有底层配置 。
+对应 [Jest](https://jestjs.io/docs/configuration) 的配置，当为 `object` 类型时，可以配置 Jest 所支持的所有底层配置 。
 
 ```js modern.config.ts
 import { defineConfig } from '@modern-js/module-tools';