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

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @modern-js/module-tools-docs
 
+## 2.25.1
+
+### Patch Changes
+
+- @modern-js/doc-tools@2.25.1
+- @modern-js/doc-plugin-auto-sidebar@2.25.1
+
 ## 2.25.0
 
 ### Minor Changes

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

@@ -2,9 +2,20 @@
 sidebar_position: 1
 ---
 
-# BuildConfig
+# buildConfig
 
-This section describes all the configuration of Module Tools for building
+`buildConfig` is a configuration option that describes how to compile and generate build artifacts. It contains all the configurations related to the build process.
+
+- **Type**: `object | object[]`
+- **Default**: `undefined`
+
+:::tip
+Before start using `buildConfig`, please read the following documentation to understand its purpose:
+
+- [Modifying Output Artifacts](/guide/basic/modify-output-product.html)
+- [In-Depth Understanding of the Build Process](/guide/advance/in-depth-about-build.html)
+
+:::
 
 ## alias
 
@@ -110,7 +121,7 @@ At this point, all static resources will be prefixed with `https://xxx/`
 
 Packaged to handle svg as a React component, options reference [svgr](https://react-svgr.com/docs/options/), plus support for two configuration items `include` and `exclude` to match the svg file to be handled
 
-- **Type**: `boolean | Object`
+- **Type**: `boolean | object`
 - **Default**: `false`
 
 When svgr feature is enabled, you can use svg as a component using the default export.
@@ -160,7 +171,7 @@ Set unmatched svg files
 
 Automatically externalize project dependencies and peerDependencies and not package them into the final bundle
 
-- **Type**: `boolean | Object`
+- **Type**: `boolean | object`
 - **Default**: `true`
 
 When we want to turn off the default handling behavior for third-party dependencies, we can do so by:
@@ -212,7 +223,7 @@ The build type, `bundle` will package your code, `bundleless` will only do the c
 
 Copies the specified file or directory into the build output directory
 
-- **Type**: `Array`
+- **Type**: `object[]`
 - **Default**: `[]`
 
 ```js
@@ -295,7 +306,7 @@ The use of SWC Transform can reduce the impact of auxiliary functions on the vol
 
 The dts file generates the relevant configuration, by default it generates.
 
-- **Type**: `false | Object`
+- **Type**: `false | object`
 - **Default**:
 
 ```js
@@ -438,21 +449,102 @@ export var yourCode = function () {
 
 Configure external dependencies that will not be packaged into the final bundle
 
-- **Type**: `(string | RegExp)[]`
+- **Type**:
+
+```ts
+type External = (string | RegExp)[];
+```
+
 - **Default**: `[]`
+- **Build Type**: `Only supported for buildType: 'bundle'`
+- **Example**:
+
+```js modern.config.ts
+export default defineConfig({
+  buildConfig: {
+    // do not bundle React
+    externals: ['react'],
+  },
+});
+```
 
 ## format
 
-The format of the js product output, where `iife` and `umd` can only take effect when `buildType` is `bundle`
+Used to set the output format of JavaScript files. The options `iife` and `umd` only take effect when `buildType` is `bundle`.
 
 - **Type**: `'esm' | 'cjs' | 'iife' | 'umd'`
 - **Default**: `cjs`
 
+### format: 'esm'
+
+`esm` stands for "ECMAScript module" and requires the runtime environment to support import and export syntax.
+
+- **Example**:
+
+```js modern.config.ts
+export default defineConfig({
+  buildConfig: {
+    format: 'esm',
+  },
+});
+```
+
+### format: 'cjs'
+
+`cjs` stands for "CommonJS" and requires the runtime environment to support exports, require, and module syntax. This format is commonly used in Node.js environments.
+
+- **Example**:
+
+```js modern.config.ts
+export default defineConfig({
+  buildConfig: {
+    format: 'cjs',
+  },
+});
+```
+
+### format: 'iife'
+
+`iife` stands for "immediately-invoked function expression" and wraps the code in a function expression to ensure that any variables in the code do not accidentally conflict with variables in the global scope. This format is commonly used in browser environments.
+
+- **Example**:
+
+```js modern.config.ts
+export default defineConfig({
+  buildConfig: {
+    format: 'iife',
+  },
+});
+```
+
+### format: 'umd'
+
+`umd` stands for "Universal Module Definition" and is used to run modules in different environments such as browsers and Node.js. Modules in UMD format can be used in various environments, either as global variables or loaded as modules using module loaders like RequireJS.
+
+- **Example**:
+
+```js modern.config.ts
+export default defineConfig({
+  buildConfig: {
+    format: 'umd',
+  },
+});
+```
+
 ## input
 
 Specify the entry file for the build, in the form of an array that can specify the directory
 
-- **Type**: `string[] | Record<string, string>`
+- **Type**:
+
+```ts
+type Input =
+  | string[];
+  | {
+      [name: string]: string;
+    }
+```
+
 - **Default**: `['src/index.ts']` in `bundle` mode, `['src']` in `bundleless` mode
 
 **Array usage:**
@@ -484,29 +576,54 @@ export default defineConfig({
 
 ## jsx
 
-Specify the compilation method of JSX, default support React17, automatically inject JSX Runtime code. If you need to support React16, set `jsx` to `transform`.
-
-> For more information about JSX Transform, you can refer to the following links:
->
-> - [React Blog](https://legacy.reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html)。
-> - [esbuild JSX](https://esbuild.github.io/api/#jsx)
->
+Specify the compilation method for JSX, which by default supports React 17 and higher versions and automatically injects JSX runtime code.
 
 - **Type**: `automatic | transform`
 - **Default**: `automatic`
 
+If you need to support React 16, you can set `jsx` to `transform`:
+
+```js modern.config.ts
+export default defineConfig({
+  buildConfig: {
+    jsx: 'transform',
+  },
+});
+```
+
+:::tip
+For more information about JSX Transform, you can refer to the following links:
+
+- [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 to produce some metadata about the build in JSON format, which can be visualized by tools such as [bundle-buddy](https://bundle-buddy.com/esbuild)
+This option is used for build analysis. When enabled, esbuild will generate metadata about the build in JSON format.
 
 - **Type**: `boolean`
 - **Default**: `false`
+- **Build Type**: `Only supported for buildType: 'bundle'`
+
+To enable `metafile` generation:
+
+```js modern.config.ts
+export default defineConfig({
+  buildConfig: {
+    buildType: 'bundle',
+    metafile: true,
+  },
+});
+```
+
+After executing the build, a `metafile-[xxx].json` file will be generated in the output directory. You can use tools like [esbuild analyze](https://esbuild.github.io/analyze/) and [bundle-buddy](https://bundle-buddy.com/esbuild) for visual analysis.
 
 ## minify
 
 Use esbuild or terser to compress code, also pass [terserOptions](https://github.com/terser/terser#minify-options)
 
-- **Type**: `'terser' | 'esbuild' | false | Object`
+- **Type**: `'terser' | 'esbuild' | false | object`
 - **Default**: `false`
 
 ```js modern.config.ts
@@ -617,8 +734,8 @@ Whether to generate sourceMap or not
 
 Sets the format of the source code. By default, the source code will be treated as EsModule. When the source code is using CommonJS, you need to set `commonjs`.
 
-- **Type**: `commonjs` | `module`
-- **Default**: `module`
+- **Type**: `'commonjs' | 'module'`
+- **Default**: `'module'`
 
 ## splitting
 
@@ -639,7 +756,7 @@ less-related configuration
 
 Refer to [less](https://less.bootcss.com/usage/#less-options) for detailed configuration
 
-- **Type**: `Object`
+- **Type**: `object`
 - **Default**: `{ javascriptEnabled: true }`
 
 ## style.less.additionalData
@@ -663,12 +780,12 @@ export default {
 
 ## style.less.implementation
 
-Configure the implementation library used by `Less`, if not specified, the built-in version used is `4.1.3`
+Configure the implementation library used by `Less`, if not specified, the built-in version used is `4.1.3`.
 
-- **Type**: `string | Object`
+- **Type**: `string | object`
 - **Default**: `undefined`
 
-Specify the implementation library for `Less` when the `Object` type is specified
+Specify the implementation library for `Less` when the `object` type is specified.
 
 ```js modern.config.ts
 export default {
@@ -702,9 +819,9 @@ sass-related configuration.
 
 ## style.sass.sassOptions
 
-Refer to [node-sass](https://github.com/sass/node-sass#options) for detailed configuration
+Refer to [node-sass](https://github.com/sass/node-sass#options) for detailed configuration.
 
-- **Type**: `Object`
+- **Type**: `object`
 - **Default**: `{}`
 
 ## style.sass.additionalData
@@ -729,12 +846,12 @@ export default {
 
 ## style.sass.implementation
 
-Configure the implementation library used by `Sass`, the built-in version used is `1.5.4` if not specified
+Configure the implementation library used by `Sass`, the built-in version used is `1.5.4` if not specified.
 
-- **Type**: `string | Object`
+- **Type**: `string | object`
 - **Default**: `undefined`
 
-Specify the implementation library for `Sass` when the `Object` type is specified
+Specify the implementation library for `Sass` when the `object` type is specified.
 
 ```js modern.config.ts
 export default {
@@ -771,14 +888,12 @@ See [PostCSS](https://github.com/postcss/postcss#options) for detailed configura
 
 **Basic usage：**
 
-``` js modern.config.ts
+```js modern.config.ts
 export default defineConfig({
   buildConfig: {
     style: {
       postcss: {
-        plugins: [
-          yourPostCSSPlugin,
-        ],
+        plugins: [yourPostCSSPlugin],
       },
     },
   },
@@ -848,7 +963,7 @@ Enable CSS Modules automatically based on the filename.
 
 CSS Modules configuration
 
-- **Type**: `Object`
+- **Type**: `object`
 - **Default**: `{}`
 
 A common configuration is `localsConvention`, which changes the class name generation rules for css modules
@@ -881,7 +996,7 @@ For detailed configuration see [postcss-modules](https://github.com/madyankin/po
 
 tailwindcss related configuration
 
-- **Type**: `Object | Function`
+- **Type**: `object | Function`
 - **Default**: `see configuration details below`
 
 <details>
@@ -902,7 +1017,7 @@ const tailwind = {
 };
 ```
 
-When the value is of type `Object`, it is merged with the default configuration via `Object.assign`.
+When the value is of type `object`, it is merged with the default configuration via `Object.assign`.
 
 When the value is of type `Function`, the object returned by the function is merged with the default configuration via `Object.assign`.
 
@@ -947,7 +1062,7 @@ export default defineConfig({
 
 Using [SWC](https://swc.rs/) provides the same ability and configuration as [`babel-plugin-import`](https://github.com/umijs/babel-plugin-import).
 
-- **Type**: `Array`
+- **Type**: `object[]`
 - **Default**: `[]`
 
 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)。
@@ -996,7 +1111,7 @@ At this point, `react` and `react-dom` will be seen as global variables imported
 
 Specifies the module name of the umd product
 
-- **Type**: `string` | `Function`
+- **Type**: `string | Function`
 - **Default**: `name => name`
 
 ```js

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

@@ -2,12 +2,12 @@
 sidebar_position: 2
 ---
 
-# BuildPreset
+# buildPreset
 
 A build preset string or preset function. Provides out-of-the-box build configuration
 
-- Type: `string | Function`
-- Default: `undefined`
+- **Type**: `string | Function`
+- **Default**: `undefined`
 
 ## string
 

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

@@ -2,15 +2,15 @@
 sidebar_position: 3
 ---
 
-# DesignSystem
+# designSystem
 
-This chapter describes the configuration related to designSystem
+This chapter describes the configuration related to designSystem.
 
 :::tip
 The Tailwind CSS feature needs to be enabled first via `pnpm run new`.
 :::
 
-- Type: `Object`
+- Type: `object`
 - Default: `see configuration details below`.
 
 <details>

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

@@ -2,16 +2,18 @@
 sidebar_position: 3
 ---
 
-# Dev Config
+# dev
 
 This section describes all configuration of Module Tools related to debugging tools.
 
-``` ts
+```ts
 export default {
   dev: {
-    storybook: {/* Storybook Config */},
+    storybook: {
+      /* Storybook Config */
+    },
   },
-}
+};
 ```
 
 ## storybook
@@ -21,36 +23,34 @@ export default {
 - Turn on Storybook debugging or install the `@modern-js/plugin-storybook` plugin.
 - Register the `@modern-js/plugin-storybook` plugin。
 
-> For more information on how to enable Storybook debugging, please refer to：[【Storybook】](guide/basic/use-micro-generator#storybook)
-
-
+> For more information on how to enable Storybook debugging, please refer to：["Storybook"](guide/basic/use-micro-generator#storybook)
 
 ### storybook.webpack
 
-- **Type**: `Object` | `Function` | `undefined`
-
+- **Type**: `object | Function | undefined`
 - **Default**: `undefined`
 
-``` ts
+```ts
 export default {
   dev: {
     storybook: {
       webpack(config) {
         return config;
       },
-    }
-  }
-}
+    },
+  },
+};
 ```
 
-You can modify the webpack configuration of the Storybook Preview-iframe via `dev.storybook.webpack`. The usage can be found in the [`tools.webpack`](https://modernjs.dev/builder/api/config-tools.html#tools.webpack) configuration of Modern.js Builder.
+You can modify the webpack configuration of the Storybook Preview-iframe via `dev.storybook.webpack`. The usage can be found in the [`tools.webpack`](https://modernjs.dev/builder/en/api/config-tools.html#toolswebpack) configuration of Modern.js Builder.
 
 ![Storybook](https://storybook.js.org/71522ac365feaf3338d7c242e53378f6/manager-preview.png)
 
-:::tip
+#### Configure Manager App
+
 For the webpack configuration of the Storybook Manager app section, you can configure it by adding the `./config/storybook/main.js` file to configure it.
 
-``` js
+```js
 // ./config/storybook/main.js
 
 module.exports = {
@@ -61,25 +61,22 @@ module.exports = {
   },
 };
 ```
-:::
 
 ### storybook.webpackChain
 
-- **Type**: `Function` | `undefined`
-
+- **Type**: `Function | undefined`
 - **Default**: `undefined`
 
-``` ts
+```ts
 export default {
   dev: {
     storybook: {
       webpackChain(chain) {
         return chain;
       },
-    }
-  }
-}
+    },
+  },
+};
 ```
 
-You can modify the webpack configuration of the Storybook Preview-iframe via `dev.storybook.webpackChain`. You can refer to Modern.js Builder's [`tools.webpackChain`](https://modernjs.dev/builder/api/config-tools.html#tools.webpackchain) configuration for how to use it.
-
+You can modify the webpack configuration of the Storybook Preview-iframe via `dev.storybook.webpackChain`. You can refer to Modern.js Builder's [`tools.webpackChain`](https://modernjs.dev/builder/en/api/config-tools.html#toolswebpackchain) configuration for how to use it.

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

@@ -2,17 +2,62 @@
 sidebar_position: 4
 ---
 
-# Plugins
+# plugins
 
 This chapter describes the configuration of the registered Module Tools plugin.
 
-- Type: `Array<ModuleToolsPlugin>`
+- **Type**: `ModuleToolsPlugin[]`
+- **Default**: `undefined`
+
+## Plugin Execution Order
+
+By default, custom plugins are executed in the order specified in the `plugins` array. The execution of built-in plugins provided by Module Tools happens before the execution of custom plugins.
+
+When plugins use fields that control the execution order, such as `pre` and `post`, the execution order is adjusted based on the declared fields. For more information, please refer to the [Relationship Between Plugins](https://modernjs.dev/en/guides/topic-detail/framework-plugin/relationship) guide.
+
+## Developing Plugins
+
+To learn how to write plugins, please refer to the [Plugin Writing Guide](/plugins/guide/getting-started).
+
+## Example
+
+### Using Plugins from npm
+
+To use plugins from npm, you need to install them using a package manager and import them in your configuration file.
+
+```js modern.config.ts
+import { myPlugin } from 'my-plugin';
+
+export default defineConfig({
+  plugins: [myPlugin()],
+});
+```
+
+#### Using Local Plugins
+
+To use plugins from a local code repository, you can directly import them using a relative path.
 
 ```js modern.config.ts
-import { examplePlugin } from '. /plugins/example';
+import { myPlugin } from './plugins/myPlugin';
+
 export default defineConfig({
-  plugins: [examplePlugin()],
+  plugins: [myPlugin()],
 });
 ```
 
-For more information on how to write plugins, check out the [[Plugin Writing Guide]](/en/plugins/guide/getting-started).
+### Plugin Configuration
+
+If a plugin provides custom configuration options, you can pass the configuration through the plugin function's parameters.
+
+```js modern.config.ts
+import { myPlugin } from 'my-plugin';
+
+export default defineConfig({
+  plugins: [
+    myPlugin({
+      foo: 1,
+      bar: 2,
+    }),
+  ],
+});
+```

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

@@ -2,7 +2,7 @@
 sidebar_position: 5
 ---
 
-# Testing
+# testing
 
 This chapter describes the test-related configuration
 
@@ -12,10 +12,10 @@ You need to enable the unit testing feature with `pnpm run new` first.
 
 ## jest
 
-- Type: `Object | Function`
+- Type: `object | Function`
 - Default: `{}`
 
-The configuration corresponding to [Jest](https://jestjs.io/docs/configuration), when of type `Object`, can be configured with all the underlying configurations supported by Jest .
+The configuration corresponding to [Jest](https://jestjs.io/docs/configuration), when of type `object`, can be configured with all the underlying configurations supported by Jest .
 
 ```js modern.config.ts
 import { defineConfig } from '@modern-js/module-tools';

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

@@ -22,7 +22,7 @@ export default defineConfig({
 
 ## Third-party dependency handling for umd products
 
-In the [[How to handle third-party dependencies]](/en/guide/advance/external-dependency) chapter, we know that we can control whether or not the project packages third-party dependencies via the [`autoExternals`](/en/api/config/build-config#autoexternal) and [`externals`](/en/api/config/build-config#externals) APIs.
+In the ["How to handle third-party dependencies"](/en/guide/advance/external-dependency) chapter, we know that we can control whether or not the project packages third-party dependencies via the [`autoExternals`](/en/api/config/build-config#autoexternal) and [`externals`](/en/api/config/build-config#externals) APIs.
 So when building umd products, we can also use it like this:
 
 <CH.Spotlight>

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

@@ -2,9 +2,9 @@
 sidebar_position: 2
 ---
 
-# Command Preview
+# CLI Commands
 
-Commands available for module engineering projects.
+CLI Commands available for Module Tools projects are as follows:
 
 ## `modern build`
 

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

@@ -6,13 +6,17 @@ sidebar_position: 3
 
 ## Default output products
 
-When the `modern build` command is used in an initialized project, the products are generated according to the default configuration supported by Module Tools. The default supported configurations are specified as follows.
+When you use the `modern build` command in an initialized project, Module Tools will generate corresponding build products based on the current configuration.
+
+The default configuration is as follows:
 
 ```ts title="modern.config.ts"
 import { moduleTools, defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({
+  // Register the CLI tool of Module Tools
   plugins: [moduleTools()],
+  // Specify the build preset configuration
   buildPreset: 'npm-library',
 });
 ```
@@ -70,11 +74,19 @@ export default defineConfig({
 });
 ```
 
-In the above code implementation, `preset.NPM_LIBRARY` corresponds to the preset string `"npm-library"`, which represents the equivalent of `"npm-library"` for multiple sets of build-related configurations. We traverse the `NPM_LIBRARY` array, which contains multiple `buildConfig` objects, using the `map` method. We made a shallow copy of the original `buildConfig` object and modified the value of the `target` after the shallow copy, specifying it as `es5`.
+In the above code implementation, `preset.NPM_LIBRARY` corresponds to the preset string `"npm-library"`, representing multiple build-related configurations equivalent to `"npm-library"`.
+
+We use the `map` method to iterate over the `NPM_LIBRARY` array, which contains multiple `buildConfig` objects. We perform a shallow copy of the original `buildConfig` object and modify the value of the `target` property in the shallow copy to be `es5`.
 
+If you want to know the specific contents included in `preset.NPM_LIBRARY`, you can refer to the [BuildPreset API](/api/config/build-preset).
+
+In addition, under the `preset` object, it not only includes `NPM_LIBRARY`, but also other similar constants.
 
 > NPM_LIBRARY`, you can check it with [BuildPreset API](/api/config/build-preset). The`preset`object contains not only`NPM_LIBRARY`, but also other similar constants.
-> We can not only use `preset.NPM_LIBRARY` to get the build configuration corresponding to `"npm-library"`, but also `preset['npm-library']` in this way.
+
+:::tip
+We can not only use `preset.NPM_LIBRARY`to get the build configuration corresponding to`"npm-library"`, but also `preset['npm-library']` in this way.
+:::
 
 So what is the `buildConfig` object here? What is the basis for the build product feature mentioned before?
 
@@ -82,7 +94,7 @@ Let's explain next.
 
 ## Build configuration (object)
 
-**`buildConfig` is a configuration object that describes how to compile and generate build products**. What was mentioned at the beginning about "_features of build products_" are actually properties supported by `buildConfig`. The currently supported properties cover the needs of most module type projects when building products. `buildConfig` not only contains some properties that products have, but also contains some features needed to build products. The following is a brief list from a classification point of view.
+**`buildConfig` is a configuration option that describes how to compile and generate build products**. What was mentioned at the beginning about "_features of build products_" are actually properties supported by `buildConfig`. The currently supported properties cover the needs of most module type projects when building products. `buildConfig` not only contains some properties that products have, but also contains some features needed to build products. The following is a brief list from a classification point of view.
 
 **The basic attributes of a build product include:**