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

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';

package/docs/zh/guide/advance/build-umd.mdx

@@ -22,7 +22,7 @@ export default defineConfig({
 
 ## umd 产物的第三方依赖处理
 
-在 [【如何处理第三方依赖】](/guide/advance/external-dependency) 章节中，我们知道可以通过 [`autoExternals`](/api/config/build-config#autoexternal) 和 [`externals`](/api/config/build-config#externals) API 来控制项目是否对第三方依赖打包。
+在 [「如何处理第三方依赖」](/guide/advance/external-dependency) 章节中，我们知道可以通过 [`autoExternals`](/api/config/build-config#autoexternal) 和 [`externals`](/api/config/build-config#externals) API 来控制项目是否对第三方依赖打包。
 因此在构建 umd 产物的过程中，我们也可以这样使用：
 
 <CH.Spotlight>

package/docs/zh/guide/basic/before-getting-started.md

@@ -14,7 +14,7 @@ sidebar_position: 1
 
 npm 是 NodeJS 的标准软件包管理器。它一开始的用途是用于下载和管理 NodeJS 包的依赖关系，但后来它逐渐变成为一个用于前端 JavaScript 的工具。
 
-**如果你已经对 npm 和 npm 包的使用方式有所了解，那么可以直接跳到[【npm 包管理器】](/guide/basic/before-getting-started#npm-包管理器)部分。**
+**如果你已经对 npm 和 npm 包的使用方式有所了解，那么可以直接跳到[「npm 包管理器」](/guide/basic/before-getting-started#npm-包管理器)部分。**
 
 ## npm 包类型项目
 

package/docs/zh/guide/basic/command-preview.md

@@ -2,9 +2,9 @@
 sidebar_position: 2
 ---
 
-# 命令预览
+# CLI 命令
 
-模块工程项目可以使用的命令：
+Module Tools 项目可以使用的 CLI 命令如下：
 
 ## `modern build`
 
@@ -60,7 +60,7 @@ Options:
 - Tailwind CSS 支持
 - Modern.js Runtime API
 
-关于这些功能，可以通过[【使用微生成器】](/guide/basic/use-micro-generator) 章节了解更多。
+关于这些功能，可以通过[「使用微生成器」](/guide/basic/use-micro-generator) 章节了解更多。
 
 ## `modern dev`
 

package/docs/zh/guide/basic/modify-output-product.md

@@ -6,20 +6,24 @@ sidebar_position: 3
 
 ## 默认输出产物
 
-当在初始化的项目里使用 `modern build` 命令的时候，会根据 Module Tools 默认支持的配置生成相应的产物。默认支持的配置具体如下：
+当你在初始化的项目里使用 `modern build` 命令的时候，Module Tools 会根据当前配置内容，生成相应的构建产物。
+
+默认的配置内容如下：
 
 ```ts title="modern.config.ts"
 import { moduleTools, defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({
+  // 注册 Module Tools 的 CLI 工具
   plugins: [moduleTools()],
+  // 指定构建预设配置
   buildPreset: 'npm-library',
 });
 ```
 
 **默认生成产物具有以下特点**：
 
-- 会生成[CommonJS](https://nodejs.org/api/modules.html#modules-commonjs-modules)和[ESM](https://nodejs.org/api/esm.html#modules-ecmascript-modules)两份产物。
+- 会生成 [CommonJS](https://nodejs.org/api/modules.html#modules-commonjs-modules) 和 [ESM](https://nodejs.org/api/esm.html#modules-ecmascript-modules) 两份产物。
 - 代码语法支持到 `ES6` ,更高级的语法将会被转换。
 - 所有的代码经过打包变成了一个文件，即进行了 **bundle** 处理。
 - 产物输出根目录为项目下的 `dist` 目录，类型文件输出的目录为 `dist/types`。
@@ -29,7 +33,7 @@ export default defineConfig({
 1. `buildPreset` 是什么？
 2. 产物的这些特点是由什么决定的？
 
-那么接下来首先解释一下 `buildPreset`。
+接下来，我们首先来了解一下 `buildPreset`。
 
 ## 构建预设
 
@@ -70,10 +74,17 @@ export default defineConfig({
 });
 ```
 
-在上面的代码实现中，`preset.NPM_LIBRARY` 与预设字符串 `"npm-library"` 是相对应的，它代表着 `"npm-library"` 等价的多组构建相关的配置。我们通过 `map` 方法遍历了 `NPM_LIBRARY` 这个数组，在这个数组中包含了多个 `buildConfig` 对象。我们将原本的 `buildConfig` 对象进行了浅拷贝，并修改了浅拷贝后 `target` 的值，将它指定为 `es5`。
+在上面的代码实现中，`preset.NPM_LIBRARY` 与预设字符串 `"npm-library"` 是相对应的，它代表与 `"npm-library"` 等价的多个构建相关的配置。
+
+我们通过 `map` 方法遍历了 `NPM_LIBRARY` 这个数组，在这个数组中包含了多个 `buildConfig` 对象。我们将原本的 `buildConfig` 对象进行了浅拷贝，并修改了浅拷贝后 `target` 的值，将它指定为 `es5`。
+
+如果你想了解 `preset.NPM_LIBRARY` 具体包含的内容，可以通过 [BuildPreset API](/api/config/build-preset) 查看。
+
+此外，在 `preset` 对象下，不仅包含了 `NPM_LIBRARY`，也包含了其他类似的常量。
 
-> 关于 `preset.NPM_LIBRARY` 具体对应的值，可以通过 [BuildPreset API](/api/config/build-preset) 查看。在 `preset` 对象下不仅包含了 `NPM_LIBRARY`，还包含了其他类似的常量。
-> 我们不仅可以使用 `preset.NPM_LIBRARY` 来获取 `"npm-library"` 对应的构建配置，也可以使用 `preset['npm-library']` 这样的方式。
+:::tip
+我们不仅可以使用 `preset.NPM_LIBRARY` 来获取 `"npm-library"` 对应的构建配置，也可以使用 `preset['npm-library']` 这样的方式。
+:::
 
 那么这里的 `buildConfig` 对象是什么呢？之前提到的构建产物特点又是根据什么呢？
 
@@ -81,7 +92,7 @@ export default defineConfig({
 
 ## 构建配置（对象）
 
-**`buildConfig` 是一个用来描述如何编译、生成构建产物的配置对象**。在最开始提到的关于“_构建产物的特点_”，其实都是 `buildConfig` 所支持的属性。目前所支持的属性覆盖了大部分模块类型项目在构建产物时的需求，`buildConfig` 不仅包含一些产物所具备的属性，也包含了构建产物所需要的一些特性功能。接下来从分类的角度简单罗列一下：
+**`buildConfig` 是一个用来描述如何编译、生成构建产物的配置项**。在最开始提到的关于“_构建产物的特点_”，其实都是 `buildConfig` 所支持的属性。目前所支持的属性覆盖了大部分模块类型项目在构建产物时的需求，`buildConfig` 不仅包含一些产物所具备的属性，也包含了构建产物所需要的一些特性功能。接下来从分类的角度简单罗列一下：
 
 **构建产物的基本属性包括：**
 

package/docs/zh/guide/best-practices/components.mdx

@@ -609,7 +609,7 @@ Tailwind CSS 提供了 [`@apply`](https://v2.tailwindcss.com/docs/functions-and-
 
 对于以下代码，在 bundle 和 bundleless 两种模式下，构建产物会有很大区别。
 
-> 所谓 bundle 和 bundleless 可以查看 [【Bundle 和 Bundleless】](/guide/advance/in-depth-about-build#bundle-和-bundleless)
+> 所谓 bundle 和 bundleless 可以查看 [「Bundle 和 Bundleless」](/guide/advance/in-depth-about-build#bundle-和-bundleless)
 
 ```tsx ./src/index.tsx
 import 'tailwindcss/utilities.css';
@@ -786,8 +786,8 @@ export default defineConfig({
 
 ## 测试组件
 
-关于如何对组件进行测试，可以参考 [【测试项目】](/guide/basic/test-your-project)。
+关于如何对组件进行测试，可以参考 [「测试项目」](/guide/basic/test-your-project)。
 
 ## 发布组件
 
-推荐使用模块工程提供版本发布功能，可以参考 [【版本管理与发布】](/guide/basic/publish-your-project)。
+推荐使用模块工程提供版本发布功能，可以参考 [「版本管理与发布」](/guide/basic/publish-your-project)。

package/docs/zh/plugins/guide/setup-function.mdx

@@ -4,7 +4,7 @@ sidebar_position: 3
 
 # Setup 函数
 
-在[【插件对象】](/plugins/guide/plugin-object) 部分我们知道插件对象包含了一个 `setup` 函数，该函数不仅包含了一个 `api` 对象参数，同时还可以返回一个 Hooks 对象。
+在[「插件对象」](/plugins/guide/plugin-object) 部分我们知道插件对象包含了一个 `setup` 函数，该函数不仅包含了一个 `api` 对象参数，同时还可以返回一个 Hooks 对象。
 
 ## 插件 API 对象
 

package/docs/zh/plugins/official-list/plugin-banner.md

@@ -39,7 +39,7 @@ export default defineConfig({
 ```
 
 :::tip
-注意：CSS 的注释不支持 `//comment` 这样的写法。详见[【CSS 注释】](https://developer.mozilla.org/zh-CN/docs/Web/CSS/Comments)
+注意：CSS 的注释不支持 `//comment` 这样的写法。详见[「CSS 注释」](https://developer.mozilla.org/zh-CN/docs/Web/CSS/Comments)
 :::
 
 ## 示例

package/docs/zh/plugins/official-list/plugin-import.mdx

@@ -3,7 +3,7 @@
 提供与 [babel-plugin-import](https://github.com/umijs/babel-plugin-import) 等价的能力和配置，基于 [SWC](https://swc.rs/) 实现。
 
 :::tip
-从 @modern-js/module-tools 2.16.0 版本开始，该插件功能内置在 module-tools 中，由 [`transformImport`](api/config/build-config.html#transformimport)
+从 `@modern-js/module-tools` v2.16.0 版本开始，该插件功能内置在 Module Tools 中，由 [`transformImport`](api/config/build-config.html#transformimport)
 配置提供。
 :::
 
@@ -34,10 +34,12 @@ export default defineConfig({
   plugins: [
     moduleTools(),
     modulePluginImport({
-      pluginImport: [{
-        libraryName: 'antd',
-        style: true,
-      }],
+      pluginImport: [
+        {
+          libraryName: 'antd',
+          style: true,
+        },
+      ],
     }),
   ],
 });
@@ -47,17 +49,17 @@ export default defineConfig({
 
 ## 配置
 
-* **类型：**
+- **类型：**
 
 ```ts
 type Options = {
   pluginImport?: ImportItem[];
-}
+};
 ```
 
 ### pluginImport
 
-* 类型：`Array`
+- 类型：`object[]`
 
 其中数组元素为一个 babel-plugin-import 的配置对象。配置对象可以参考 [options](https://github.com/umijs/babel-plugin-import#options)。
 
@@ -76,7 +78,7 @@ export default defineConfig({
         {
           libraryName: 'foo',
           style: true,
-        }
+        },
       ],
     }),
   ],
@@ -117,10 +119,12 @@ export default defineConfig({
   plugins: [
     moduleTools(),
     modulePluginImport({
-      pluginImport: [{
-        libraryName: 'foo',
-        customName: 'foo/es/{{ member }}'
-      }],
+      pluginImport: [
+        {
+          libraryName: 'foo',
+          customName: 'foo/es/{{ member }}',
+        },
+      ],
     }),
   ],
 });
@@ -138,16 +142,19 @@ export default defineConfig({
   plugins: [
     moduleTools(),
     modulePluginImport({
-      pluginImport: [{
-        libraryName: 'foo',
-        customName: 'foo/es/{{ member }}'
-      }],
+      pluginImport: [
+        {
+          libraryName: 'foo',
+          customName: 'foo/es/{{ member }}',
+        },
+      ],
     }),
   ],
 });
 ```
 
 ---
+
 转换后:
 
 ```ts
@@ -168,10 +175,12 @@ export default defineConfig({
   plugins: [
     moduleTools(),
     modulePluginImport({
-      pluginImport: [{
-        libraryName: 'foo',
-        customName: 'foo/es/{{ kebabCase member }}',
-      }],
+      pluginImport: [
+        {
+          libraryName: 'foo',
+          customName: 'foo/es/{{ kebabCase member }}',
+        },
+      ],
     }),
   ],
 });

package/package.json

@@ -9,15 +9,15 @@
     "directory": "packages/document/module-doc"
   },
   "license": "MIT",
-  "version": "2.25.0",
+  "version": "2.25.1",
   "main": "index.js",
   "dependencies": {
     "@code-hike/mdx": "^0.7.4",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "shiki": "^0.11.1",
-    "@modern-js/doc-plugin-auto-sidebar": "2.25.0",
-    "@modern-js/doc-tools": "2.25.0"
+    "@modern-js/doc-plugin-auto-sidebar": "2.25.1",
+    "@modern-js/doc-tools": "2.25.1"
   },
   "scripts": {
     "dev": "modern dev",