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

package/CHANGELOG.md

@@ -1,11 +1,24 @@
 # @modern-js/module-tools-docs
 
-## 2.24.1
+## 2.25.1
 
 ### Patch Changes
 
-- @modern-js/doc-plugin-auto-sidebar@2.24.1
-- @modern-js/doc-tools@2.24.1
+- @modern-js/doc-tools@2.25.1
+- @modern-js/doc-plugin-auto-sidebar@2.25.1
+
+## 2.25.0
+
+### Minor Changes
+
+- ba6f5a6: docs: update module doc FAQ contents
+  docs: 更新 module 文档的 FAQ 内容
+
+### Patch Changes
+
+- Updated dependencies [9aa2c25]
+  - @modern-js/doc-tools@2.25.0
+  - @modern-js/doc-plugin-auto-sidebar@2.25.0
 
 ## 2.24.0
 

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,23 +449,106 @@ 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:**
+
 ```js modern.config.ts
 export default {
   buildConfig: {
@@ -463,25 +557,73 @@ export default {
 };
 ```
 
+**Object usage:**
+
+When you need to modify the output file name in bundle mode, you can use an object configuration.
+
+**The key of the object is the file name of the output, and the value is the file path of the source code.**
+
+```js modern.config.ts
+export default defineConfig({
+  buildConfig: {
+    format: 'esm',
+    input: {
+      'index.esm': './src/index.ts',
+    },
+  },
+});
+```
+
 ## jsx
 
-Specify the compilation method of jsx, default support React17, automatically inject jsx runtime code
+Specify the compilation method for JSX, which by default supports React 17 and higher versions and automatically injects JSX runtime code.
 
-- **Type**: `automatic | classic`
+- **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
@@ -592,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
 
@@ -614,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
@@ -638,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 {
@@ -677,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
@@ -704,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 {
@@ -744,6 +886,20 @@ export default {
 
 See [PostCSS](https://github.com/postcss/postcss#options) for detailed configuration
 
+**Basic usage：**
+
+```js modern.config.ts
+export default defineConfig({
+  buildConfig: {
+    style: {
+      postcss: {
+        plugins: [yourPostCSSPlugin],
+      },
+    },
+  },
+});
+```
+
 ## style.inject
 
 Configure whether to insert CSS styles into JavaScript code in bundle mode.
@@ -807,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
@@ -840,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>
@@ -861,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`.
 
@@ -906,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)。
@@ -955,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';