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

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

@@ -605,7 +605,7 @@ When adding styles using HTML class names, by default Tailwind will not only add
 
 For the following code, there is a big difference between the bundle and bundleless modes of building products.
 
-> The so-called bundle and bundleless can be found in [[Bundle and Bundleless]](/en/guide/advance/in-depth-about-build#bundle- and-bundleless)
+> The so-called bundle and bundleless can be found in ["Bundle and Bundleless"](/en/guide/advance/in-depth-about-build#bundle- and-bundleless)
 
 ```tsx ./src/index.tsx
 import 'tailwindcss/utilities.css';
@@ -782,8 +782,8 @@ If you have special needs for the build product directory structure, you can use
 
 ## Testing components
 
-For more information on how to test components, please refer to [[Test project]](/en/guide/basic/test-your-project).
+For more information on how to test components, please refer to ["Test project"](/en/guide/basic/test-your-project).
 
 ## Releasing components
 
-It is recommended to use module project to provide version publishing function, you can refer to [[Versioning and publishing]](/en/guide/basic/publish-your-project).
+It is recommended to use module project to provide version publishing function, you can refer to ["Versioning and publishing"](/en/guide/basic/publish-your-project).

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

@@ -4,7 +4,7 @@ sidebar_position: 3
 
 # Setup function
 
-In the [[Plugin object]](/plugins/guide/plugin-object) section we know that the plug-in object contains a `setup` function that not only contains an `api` object parameter, but also returns a Hooks object.
+In the ["Plugin object"](/plugins/guide/plugin-object) section we know that the plug-in object contains a `setup` function that not only contains an `api` object parameter, but also returns a Hooks object.
 
 ## Plugin API objects
 

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

@@ -39,7 +39,7 @@ export default defineConfig({
 ```
 
 :::tip
-Note: CSS comments do not support the `//comment` syntax. Refer to [【CSS Comments】](https://developer.mozilla.org/en-US/docs/Web/CSS/Comments)
+Note: CSS comments do not support the `//comment` syntax. Refer to ["CSS Comments"](https://developer.mozilla.org/en-US/docs/Web/CSS/Comments)
 :::
 
 ## Example

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

@@ -3,7 +3,7 @@
 Using [SWC](https://swc.rs/) provides the same ability and configuration as [`babel-plugin-import`](https://github.com/umijs/babel-plugin-import).
 
 :::tip
-Since @modern-js/module-tools version >= 2.16.0, this plugin functionality is built into module-tools and is provided by [`transformImport`](api/config/build-config.html#transformimport).
+Since `@modern-js/module-tools` version >= v2.16.0, this plugin functionality is built into Module Tools and is provided by [`transformImport`](api/config/build-config.html#transformimport).
 :::
 
 ## Quick Start
@@ -26,17 +26,19 @@ pnpm add @modern-js/plugin-module-import -D
 In Module Tools, you can register plugins in the following way:
 
 ```ts
-import { moduleTools, defineConfig  } from '@modern-js/module-tools';
+import { moduleTools, defineConfig } from '@modern-js/module-tools';
 import { modulePluginImport } from '@modern-js/plugin-module-import';
 
 export default defineConfig({
   plugins: [
     moduleTools(),
     modulePluginImport({
-      pluginImport: [{
-        libraryName: 'antd',
-        style: true,
-      }],
+      pluginImport: [
+        {
+          libraryName: 'antd',
+          style: true,
+        },
+      ],
     }),
   ],
 });
@@ -46,17 +48,17 @@ This way we can use the ability of automatic import in Module Tools.
 
 ## Configurations
 
-* **Type**:
+- **Type**:
 
 ```ts
 type Options = {
   pluginImport?: ImportItem[];
-}
+};
 ```
 
 ### pluginImport
 
-* **Type**: `Array`
+- **Type**: `object[]`
 
 The elements of the array are configuration objects for `babel-plugin-import`, which can be referred to [options](https://github.com/umijs/babel-plugin-import#options)。
 
@@ -64,7 +66,7 @@ The elements of the array are configuration objects for `babel-plugin-import`, w
 
 ```ts
 import { modulePluginImport } from '@modern-js/plugin-module-import';
-import { moduleTools, defineConfig  } from '@modern-js/module-tools';
+import { moduleTools, defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({
   plugins: [
@@ -75,7 +77,7 @@ export default defineConfig({
         {
           libraryName: 'foo',
           style: true,
-        }
+        },
       ],
     }),
   ],
@@ -110,16 +112,18 @@ Add the following configuration on the right-hand side:
 
 ```ts
 import { modulePluginImport } from '@modern-js/plugin-module-import';
-import { moduleTools, defineConfig  } from '@modern-js/module-tools';
+import { moduleTools, defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({
   plugins: [
     moduleTools(),
     modulePluginImport({
-      pluginImport: [{
-        libraryName: 'foo',
-        customName: 'foo/es/{{ member }}'
-      }],
+      pluginImport: [
+        {
+          libraryName: 'foo',
+          customName: 'foo/es/{{ member }}',
+        },
+      ],
     }),
   ],
 });
@@ -135,16 +139,19 @@ import { modulePluginImport } from '@modern-js/plugin-module-import';
 export default defineConfig({
   plugins: [
     modulePluginImport({
-      pluginImport: [{
-        libraryName: 'foo',
-        customName: 'foo/es/{{ member }}'
-      }],
+      pluginImport: [
+        {
+          libraryName: 'foo',
+          customName: 'foo/es/{{ member }}',
+        },
+      ],
     }),
   ],
 });
 ```
 
 ---
+
 After transformation:
 
 ```ts
@@ -159,16 +166,18 @@ The template used here is [handlebars](https://handlebarsjs.com). There are some
 
 ```ts focus=8:8
 import { modulePluginImport } from '@modern-js/plugin-module-import';
-import { moduleTools, defineConfig  } from '@modern-js/module-tools';
+import { moduleTools, defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({
   plugins: [
     moduleTools(),
     modulePluginImport({
-      pluginImport: [{
-        libraryName: 'foo',
-        customName: 'foo/es/{{ kebabCase member }}',
-      }],
+      pluginImport: [
+        {
+          libraryName: 'foo',
+          customName: 'foo/es/{{ kebabCase member }}',
+        },
+      ],
     }),
   ],
 });

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,105 @@ 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`
+- 类型：`'esm' | 'cjs' | 'iife' | 'umd'`
+- 默认值：`cjs`
+
+### format: 'esm'
+
+esm 代表 "ECMAScript 模块"，它需要运行环境支持 import 和 export 语法。
+
+- 示例：
+
+```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']`
 
 **数组用法：**
 
@@ -483,28 +575,55 @@ export default defineConfig({
 
 ## jsx
 
-指定 JSX 的编译方式，默认支持 React17 以上，自动注入 JSX 运行时代码。如果需要支持 React16，则设置 `jsx` 为 `transform`。
+指定 JSX 的编译方式，默认支持 React 17 及更高版本，自动注入 JSX 运行时代码。
 
-> 关于 JSX Transform，可以参考以下链接：
->
-> - [React Blog](https://legacy.reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html)。
-> - [esbuild JSX](https://esbuild.github.io/api/#jsx)
->
 - 类型： `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
@@ -616,8 +735,8 @@ export default defineConfig({
 
 设置源码的格式。默认情况下，会将源码作为 EsModule 进行处理。当源码使用的是 CommonJS 的时候，需要设置 `commonjs`。
 
-- 类型：`commonjs` | `module`
-- 默认值：`module`
+- 类型：`'commonjs' | 'module'`
+- 默认值：`'module'`
 
 ## splitting
 
@@ -638,7 +757,7 @@ less 相关配置。
 
 详细配置参考 [less](https://less.bootcss.com/usage/#less-options)。
 
-- 类型： `Object`
+- 类型： `object`
 - 默认值： `{ javascriptEnabled: true }`
 
 ## style.less.additionalData
@@ -664,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({
@@ -703,7 +822,7 @@ Sass 相关配置。
 
 详细配置参考 [node-sass](https://github.com/sass/node-sass#options)
 
-- 类型： `Object`
+- 类型： `object`
 - 默认值： `{}`
 
 ## style.sass.additionalData
@@ -730,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({
@@ -770,14 +889,12 @@ export default defineConfig({
 
 **基础使用：**
 
-``` js modern.config.ts
+```js modern.config.ts
 export default defineConfig({
   buildConfig: {
     style: {
       postcss: {
-        plugins: [
-          yourPostCSSPlugin,
-        ],
+        plugins: [yourPostCSSPlugin],
       },
     },
   },
@@ -847,9 +964,9 @@ style_inject_es_default(css_248z);
 
 ## style.modules
 
-CSS Modules 配置
+CSS Modules 配置。
 
-- 类型： `Object`
+- 类型： `object`
 - 默认值： `{}`
 
 一个常用的配置是 `localsConvention`，它可以改变 CSS Modules 的类名生成规则。
@@ -874,7 +991,7 @@ export default defineConfig({
 }
 ```
 
-你可以使用 `styles.boxTitle` 来访问
+你可以使用 `styles.boxTitle` 来访问。
 
 详细配置查看 [postcss-modules](https://github.com/madyankin/postcss-modules#usage)
 
@@ -882,7 +999,7 @@ export default defineConfig({
 
 Tailwind CSS 相关配置。
 
-- 类型： `Object | Function`
+- 类型： `object | Function`
 - 默认值： `见下方配置详情`
 
 <details>
@@ -903,7 +1020,7 @@ const tailwind = {
 };
 ```
 
-值为 `Object` 类型时，与默认配置通过 `Object.assign` 合并。
+值为 `object` 类型时，与默认配置通过 `Object.assign` 合并。
 
 值为 `Function` 类型时，函数返回的对象与默认配置通过 `Object.assign` 合并。
 
@@ -948,7 +1065,7 @@ export default defineConfig({
 
 提供与 babel-plugin-import 等价的能力和配置，基于 SWC 实现。
 
-- 类型：`Array`
+- 类型：`object[]`
 - 默认值：`[]`
 
 数组元素为一个 babel-plugin-import 的配置对象。配置对象可以参考 [options](https://github.com/umijs/babel-plugin-import#options)。
@@ -971,7 +1088,7 @@ export default defineConfig({
 
 ### 注意事项
 
-参考[【Import 插件——注意事项】](plugins/official-list/plugin-import.html#注意事项)
+参考[「Import 插件——注意事项」](plugins/official-list/plugin-import.html#注意事项)
 
 ## umdGlobals
 
@@ -997,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) 配置。