@modern-js/module-tools-docs 2.32.1 → 2.33.0

package/.eslintrc.js

@@ -5,7 +5,7 @@ module.exports = {
     tsconfigRootDir: __dirname,
     project: ['./tsconfig.json'],
   },
-  ignorePatterns: ['modern.config.ts'],
+  ignorePatterns: ['rspress.config.ts'],
   rules: {
     'babel/no-unused-expressions': 0,
     'react/jsx-filename-extension': 0,

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @modern-js/module-tools-docs
 
+## 2.33.0
+
+### Patch Changes
+
+- bc1f8da: feat(builder): support custom logger in dev server
+
+  feat(builder): 支持自定义 logger
+
+- Updated dependencies [db9a700]
+  - @modern-js/doc-plugin-auto-sidebar@2.33.0
+
 ## 2.32.1
 
 ### Patch Changes

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

@@ -7,7 +7,6 @@ sidebar_position: 1
 `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:
@@ -523,7 +522,7 @@ Used to set the output format of JavaScript files. The options `iife` and `umd`
 - **Type**: `'esm' | 'cjs' | 'iife' | 'umd'`
 - **Default**: `cjs`
 
-### format: 'esm'
+### format: esm
 
 `esm` stands for "ECMAScript module" and requires the runtime environment to support import and export syntax.
 
@@ -537,7 +536,7 @@ export default defineConfig({
 });
 ```
 
-### format: 'cjs'
+### 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.
 
@@ -551,7 +550,7 @@ export default defineConfig({
 });
 ```
 
-### format: 'iife'
+### 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.
 
@@ -1086,13 +1085,10 @@ For detailed configuration see [postcss-modules](https://github.com/madyankin/po
 
 ## style.tailwindcss
 
-tailwindcss related configuration
+Used to modify the configuration of [Tailwind CSS](https://tailwindcss.com/docs/configuration).
 
 - **Type**: `object | Function`
-- **Default**: `see configuration details below`
-
-<details>
-  <summary>Tailwind CSS configuration details</summary>
+- **Default**:
 
 ```js title="modern.config.ts"
 const tailwind = {
@@ -1104,7 +1100,13 @@ const tailwind = {
 };
 ```
 
-</details>
+### Enabling Tailwind CSS
+
+Before using `style.tailwindcss`, you need to enable the Tailwind CSS plugin for Module Tools.
+
+Please refer to the section [Using Tailwind CSS](/guide/best-practices/use-tailwindcss.html) for instructions on how to enable it.
+
+### Type
 
 When the value is of type `object`, it is merged with the default configuration via `Object.assign`.
 
@@ -1114,7 +1116,10 @@ The rest of the usage is the same as Tailwind CSS: [Quick Portal](https://tailwi
 
 ### Notes
 
-Please note that if you are using the [designSystem](/api/config/design-system) configuration option simultaneously, the `theme` configuration of Tailwind CSS will be overridden by the value of `designSystem`.
+Please note that:
+
+- If you are using both the `tailwind.config.{ts,js}` file and `tools.tailwindcss` option, the configuration defined in `tools.tailwindcss` will take precedence and override the content defined in `tailwind.config.{ts,js}`.
+- If you are using the `designSystem` configuration option simultaneously, the `theme` configuration of Tailwind CSS will be overridden by the value of `designSystem`.
 
 The usage of other configurations follows the same approach as the official usage of Tailwind CSS. Please refer to [tailwindcss - Configuration](https://tailwindcss.com/docs/configuration) for more details.
 
@@ -1176,8 +1181,6 @@ export default defineConfig({
 });
 ```
 
-### Notes
-
 Reference the [Import Plugin - Notes](plugins/official-list/plugin-import.html#Notes)
 
 ## transformLodash
@@ -1189,8 +1192,6 @@ This optimization is implemented using [babel-plugin-lodash](https://www.npmjs.c
 - **Type**: `boolean`
 - **Default**: `true`
 
-### Example
-
 This option is enabled by default, and Module Tools will automatically redirects the code references of `lodash` to sub-paths.
 
 For example:
@@ -1267,7 +1268,7 @@ At this point the umd artifact will go to mount on `global.myLib`
 
 - The module name of the umd artifact must not conflict with the global variable name.
 - Module names will be converted to camelCase, e.g. `my-lib` will be converted to `myLib`, refer to [toIdentifier](https://github.com/babel/babel/blob/main/packages/babel-types/src/converters/toIdentifier.ts).
-:::
+  :::
 
 Also the function form can take one parameter, which is the output path of the current package file
 

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

@@ -7,21 +7,8 @@ sidebar_position: 2
 A build preset string or preset function. Provides out-of-the-box build configuration
 
 - **Type**: `string | Function`
-- **Default**: `undefined`
 
-## string
-
-The string form allows you to use the built-in presets directly
-
-```js title="modern.config.ts"
-import { defineConfig } from '@modern-js/module-tools';
-
-export default defineConfig({
-  buildPreset: 'npm-library',
-});
-```
-
-### `'npm-library'`
+### `npm-library`
 
 Library generic schema used under class [NPM](https://www.npmjs.com/) package manager, contains `esm` and `cjs` Bundle products, and includes a type file.
 
@@ -68,7 +55,7 @@ export const buildConfig = [
 ];
 ```
 
-### `'npm-library-with-umd'`
+### `npm-library-with-umd`
 
 Used under class [NPM](https://www.npmjs.com/) package manager, and Library supports a similar pattern to [unpkg](https://unpkg.com/). Additional `umd` artifacts are provided on top of the pre-defined `npm-library`.
 
@@ -114,7 +101,7 @@ export const buildConfig = [
 ];
 ```
 
-### `'npm-component'`
+### `npm-component`
 
 A generic pattern for components (libraries) used under the class [NPM](https://www.npmjs.com/) package manager. Contains both `esm` and `cjs` Bundleless artifacts (for easy _[Tree shaking](https://developer.mozilla.org/zh-CN/docs/Glossary/Tree_shaking)_ optimization), as well as including a copy of the type file.
 
@@ -154,7 +141,7 @@ export const buildConfig = [
 ];
 ```
 
-### `'npm-component-with-umd'`
+### `npm-component-with-umd`
 
 Component (library) used under class [NPM](https://www.npmjs.com/) package manager, with support for class [unpkg](https://unpkg.com/) schema. Additional `umd` artifacts are provided on top of the pre-defined `npm-component`.
 
@@ -198,7 +185,7 @@ export const buildConfig = [
 ];
 ```
 
-### About the ECMAScript versions supported by the presets and `{es5.... .esnext}`
+### `npm-library-{es5...esnext}`
 
 When you want to use a `buildPreset` preset that supports other ECMAScript versions, you can directly add the supported versions to the `'npm-library'`, `'npm-library-with-umd'`, `'npm-component'`, `'npm-component-with-umd'` presets.
 
@@ -212,11 +199,11 @@ export default defineConfig({
 });
 ```
 
-## Function
+## string / Function
 
-The way the function is configured, you can get the preset value from the `preset` parameter and then modify the build configuration inside to customize your build configuration.
+The buildPreset not only supports basic string forms, but also function forms, which can obtain the default values we provide through the preset or extend Preset parameter and then modify them.
 
-The following is an example of how a function can be configured to compress a build product.
+Here are two examples using preset and extend Preset:
 
 ```js title="modern.config.ts"
 import { defineConfig } from '@modern-js/module-tools';
@@ -225,63 +212,15 @@ export default defineConfig({
   buildPreset({ preset }) {
     const { NPM_LIBRARY } = preset;
     return NPM_LIBRARY.map(config => {
-      config.minify = {
-        compress: {
-          drop_console: true,
-        },
+      config.define = {
+        VERSION: '1.0.1',
       };
       return config;
     });
   },
 });
 ```
-
-### Function Parameters
-
-The function form of `buildPreset` contains a function parameter in the form of an object. The object contains the following fields.
-
-- `preset`
-- `extendPreset`
-
-#### `preset`
-
-Type: **Object**
-
-Contains the build configurations corresponding to all available build presets. Build configurations can be used by means of the strings supported by `buildPreset` or by means of underscore commands for those strings. The following are examples of the use of both approaches.
-
-- Use the strings supported by `buildPreset`.
-
-```ts title="modern.config.ts"
-import { defineConfig } from '@modern-js/module-tools';
-
-export default defineConfig({
-  buildPreset({ preset }) {
-    return preset['npm-library'];
-  },
-});
-```
-
-- Use the underscore naming convention for strings supported by `buildPreset`.
-
-```ts title="modern.config.ts"
-import { defineConfig } from '@modern-js/module-tools';
-
-export default defineConfig({
-  buildPreset({ preset }) {
-    return preset.NPM_LIBRARY;
-  },
-});
-```
-
-#### `extendPreset`
-
-Type: `Function`
-
-Tool function for extending a `buildPreset` to modify the build configuration corresponding to the `buildPreset`.
-
-> The base uses something like `{...oldBuildConfig, ...extendBuildConfig}` approach to processing.
-
-For example, adding the `define` configuration to the `'npm-library'` build preset.
+In the `extend Preset`, lodash.merge is used for configuration merge.
 
 ```ts title="modern.config.ts"
 import { defineConfig } from '@modern-js/module-tools';

package/docs/en/guide/advance/asset.mdx

@@ -19,7 +19,7 @@ For the handling of static files, the module project currently supports the foll
 - Set the static resource path to `. /assets`.
 - Files less than **10kb** will be inlined into the code.
 
-### Example
+## Example
 
 Let us look at the following example:
 

package/docs/en/guide/advance/copy.md

@@ -13,13 +13,11 @@ We can use the Copy tool via the [`buildConfig.copy`](/en/api/config/build-confi
 - [`patterns`](/en/api/config/build-config#copypatterns)
 - [`options`](/en/api/config/build-config#copyoptions)
 
-It is recommended to spend some time getting to know them before you start learning.
-
 ## API Description
 
-`copy.patterns` 用于寻找复制的文件以及配置输出的路径。
+`copy.patterns` is used to find files to be copied and configure the output path.
 
-其中 `patterns.from` 用于指定要复制的文件或者目录。它接收 Glob 形式字符串或具体路径。Glob 形式字符串是指 [fast-glob pattern-syntax](https://github.com/mrmlnc/fast-glob#pattern-syntax)。因此我们可以按照如下两种方式使用它：
+The `patterns.from` parameter is used to specify the file or directory to be copied. It accepts either a Glob pattern string or a specific path. A Glob pattern string refers to the [fast-glob pattern syntax](https://github.com/mrmlnc/fast-glob#pattern-syntax). Therefore, we can use it in two ways as follows:
 
 ```ts
 export default defineConfig({
@@ -34,9 +32,10 @@ export default defineConfig({
 });
 ```
 
-`patterns.context` 一般和 `patterns.from` 配合使用，默认情况下它的值与 [`buildConfig.sourceDir`](/api/config/build-config#sourcedir) 相同，因此我们可以按照如下方式指定 `src/data.json` 文件为要复制的文件：
 
-> 默认情况下，`buildConfig.sourceDir` 为 `src`
+The `patterns.context` parameter is generally used in conjunction with `patterns.from`. By default, its value is the same as [`buildConfig.sourceDir`](/api/config/build-config#sourcedir). Therefore, we can specify the file `src/data.json` to be copied in the following way:
+
+> By default, `buildConfig.sourceDir` is set to `src`.
 
 ```ts
 export default defineConfig({
@@ -50,7 +49,7 @@ export default defineConfig({
 });
 ```
 
-当指定的文件不在源码目录的时候，可以修改 `context` 配置。例如指定项目目录下的 `temp/index.html` 为要复制的文件：
+When the specified file is not in the source code directory, you can modify the `context` configuration. For example, to specify the file `temp/index.html` in the project directory to be copied:
 
 ```ts
 import path from 'path';
@@ -70,7 +69,7 @@ export default defineConfig({
 });
 ```
 
-`patterns.to` 用于指定复制文件的输出路径，默认情况下它的值为 [`buildConfig.outDir`](/api/config/build-config#outDir)对应的值。因此我们按照如下方式将 `src/index.html` 复制到 `dist` 目录下：
+The `patterns.to` parameter is used to specify the output path for the copied files. By default, its value corresponds to [buildConfig.outDir](/api/config/build-config#outDir). Therefore, we can copy `src/index.html` to the `dist` directory as follows:
 
 ```ts
 export default defineConfig({
@@ -82,18 +81,18 @@ export default defineConfig({
 });
 ```
 
-当我们配置了 `patterns.to` 的时候：
+When we configure `patterns.to`:
 
-- 如果是相对路径，则该路径会相对于 `buildConfig.outDir` 计算出复制文件输出的绝对路径。
-- 如果是绝对路径，则会直接使用该值。
+- If it is a relative path, the path will be calculated relative to `buildConfig.outDir` to determine the absolute path for copying the files.
+- If it is an absolute path, the value will be used directly.
 
-最后 `patterns.globOptions` 用于配置寻找复制文件 [globby](https://github.com/sindresorhus/globby) 对象，其配置可参考：
+Finally, `patterns.globOptions` is used to configure the [globby](https://github.com/sindresorhus/globby) object for finding files to copy. Its configuration can be referenced from:
 
 - [globby.options](https://github.com/sindresorhus/globby#options)
 
-## 不同场景使用示例
+## Examples of Different Scenarios
 
-### 将文件复制文件
+### Copying Files
 
 ```ts
 export default defineConfig({
@@ -117,7 +116,7 @@ export default defineConfig({
 });
 ```
 
-### 将文件复制到目录
+### Copying Files to a Directory
 
 ```ts
 export default defineConfig({
@@ -141,7 +140,7 @@ export default defineConfig({
 });
 ```
 
-### 从目录复制到目录
+### Copying from Directory to Directory
 
 ```ts
 export default defineConfig({
@@ -168,7 +167,7 @@ export default defineConfig({
 });
 ```
 
-### 从目录到文件
+### Copying from Directory to File
 
 ```ts
 export default defineConfig({
@@ -195,7 +194,7 @@ export default defineConfig({
 });
 ```
 
-### 使用 Glob
+### Using Glob
 
 ```ts
 export default defineConfig({

package/docs/en/guide/advance/external-dependency.mdx

@@ -2,7 +2,7 @@
 sidebar_position: 4
 ---
 
-# How to handle third-party dependencies
+# Handle third-party dependencies
 
 Generally, third-party dependencies required by a project can be installed via the `install` command in the package manager. After the third-party dependencies are successfully installed, they will generally appear under `dependencies` and `devDependencies` in the project `package.json`.
 

package/docs/en/guide/advance/in-depth-about-build.md

@@ -12,43 +12,43 @@ If you are not familiar with `buildConfig`, please read [modify-output-product](
 
 In this chapter we'll dive into the use of certain build configurations and understand what happens when the `modern build` command is executed.
 
-## In-depth understanding of `buildConfig`
+## buildConfig
 
-### Bundle and Bundleless
+### `bundle` / `bundleless`
 
-So first let's understand Bundle and Bundleless.
+So first let's understand bundle and bundleless.
 
-A Bundle is a package of build products, which may be a single file or multiple files based on a certain [code splitting strategy](https://esbuild.github.io/api/#splitting).
+A bundle is a package of build products, which may be a single file or multiple files based on a certain [code splitting strategy](https://esbuild.github.io/api/#splitting).
 
-Bundleless, on the other hand, means that each source file is compiled and built separately, but not bundled together. Each output file can be found with its corresponding source code file. The process of **Bundleless build can also be understood as the process of code conversion of source files only**.
+bundleless, on the other hand, means that each source file is compiled and built separately, but not bundled together. Each output file can be found with its corresponding source code file. The process of **bundleless build can also be understood as the process of code conversion of source files only**.
 
 They have their own benefits.
 
-- Bundle can reduce the size of build artifacts and also pre-package dependencies to reduce the size of installed dependencies. Packaging libraries in advance can speed up application project builds.
-- Bundleless maintains the original file structure and is more conducive to debugging and tree shaking.
+- bundle can reduce the size of build artifacts and also pre-package dependencies to reduce the size of installed dependencies. Packaging libraries in advance can speed up application project builds.
+- bundleless maintains the original file structure and is more conducive to debugging and tree shaking.
 
 :::warning
-Bundleless is a single file compilation mode, so for type references and exports you need to add the `type` field, e.g. `import type { A } from '. /types`
+bundleless is a single file compilation mode, so for type references and exports you need to add the `type` field, e.g. `import type { A } from '. /types`
 :::
 
-In `buildConfig` you can specify whether the current build task is Bundle or Bundleless by using [`buildConfig.buildType`](/en/api/config/build-config#buildtype).
+In `buildConfig` you can specify whether the current build task is bundle or bundleless by using [`buildConfig.buildType`](/en/api/config/build-config#buildtype).
 
-### Relationship between `input` and `sourceDir`
+### `input` / `sourceDir`
 
-[`buildConfig.input`](/en/api/config/build-config#input) is used to specify the file path or directory path where the source code is read, and its default value differs between Bundle and Bundleless builds.
+[`buildConfig.input`](/en/api/config/build-config#input) is used to specify the file path or directory path where the source code is read, and its default value differs between bundle and bundleless builds.
 
 - When `buildType: 'bundle'`, `input` defaults to `src/index.(j|t)sx?`
 - When `buildType: 'bundleless'`, `input` defaults to `['src']`
 
 :::warning
-It is recommended that you do not specify multiple source file directories during a Bundleless build, as unintended results may occur. Bundleless builds with multiple source directories are currently in an unstable stage.
+It is recommended that you do not specify multiple source file directories during a bundleless build, as unintended results may occur. bundleless builds with multiple source directories are currently in an unstable stage.
 :::
 
-We know from the defaults: **Bundle builds can generally specify a file path as the entry point to the build, while Bundleless builds are more expected to use directory paths to find source files**.
+We know from the defaults: **bundle builds can generally specify a file path as the entry point to the build, while bundleless builds are more expected to use directory paths to find source files**.
 
 #### Object type of `input`
 
-In addition to setting `input` to an array, you can also set it to an object during the Bundle build process. **By using the object form, we can modify the name of the file that the build artifacts outputs**. So for the following example, `. /src/index.ts` corresponds to the path of the build artifacts file as `. /dist/main.js`.
+In addition to setting `input` to an array, you can also set it to an object during the bundle build process. **By using the object form, we can modify the name of the file that the build artifacts outputs**. So for the following example, `. /src/index.ts` corresponds to the path of the build artifacts file as `. /dist/main.js`.
 
 ```js title="modern.config.ts"
 import { defineConfig } from '@modern-js/module-tools';
@@ -63,7 +63,7 @@ export default defineConfig({
 });
 ```
 
-The Bundleless build process also supports such use, but it is not recommended.
+The bundleless build process also supports such use, but it is not recommended.
 
 #### `sourceDir`
 
@@ -74,10 +74,10 @@ The Bundleless build process also supports such use, but it is not recommended.
 
 In general:
 
-- **During the Bundleless build process, the values of `sourceDir` and `input` should be the same, and their default values are both `src`**.
-- It is rarely necessary to use `sourceDir` during the Bundle build process.
+- **During the bundleless build process, the values of `sourceDir` and `input` should be the same, and their default values are both `src`**.
+- It is rarely necessary to use `sourceDir` during the bundle build process.
 
-### Declaration Type Files
+### dts
 
 The [`buildConfig.dts`](/en/api/config/build-config#dts) configuration is mainly used for type file generation.
 
@@ -110,7 +110,7 @@ The **Module Tools also supports bundling of type files**, although care needs t
 
 #### Alias Conversion
 
-During the Bundleless build process, if an alias appears in the source code, e.g.
+During the bundleless build process, if an alias appears in the source code, e.g.
 
 ```js title="./src/index.ts"
 import utils from '@common/utils';
@@ -121,9 +121,8 @@ Normally, the type files generated with `tsc` will also contain these aliases. H
 - Alias conversion is possible for code of the form `import '@common/utils'` or `import utils from '@common/utils'`.
 - Aliasing is possible for code of the form `export { utils } from '@common/utils'`.
 
-However, there are some cases that cannot be handled at this time.
-
-- Output types of the form `Promise<import('@common/utils')>` cannot be converted at this time.
+However, there are some cases that cannot be handled at this time.Output types of the form `Promise<import('@common/utils')>` cannot be converted at this time.
+You can discuss it [here](https://github.com/web-infra-dev/modern.js/discussions/4511)
 
 #### Some examples of the use of `dts`
 
@@ -240,8 +239,8 @@ declare const YOUR_ADD_GLOBAL_VAR;
 When the `modern build` command is executed, the
 
 - Clear the output directory according to `buildConfig.outDir`.
-- Compile `js/ts` source code to generate the JS build artifacts for Bundle/Bundleless.
-- Generate Bundle/Bundleless type files using `tsc`.
+- Compile `js/ts` source code to generate the JS build artifacts for bundle/bundleless.
+- Generate bundle/bundleless type files using `tsc`.
 - Handle Copy tasks.
 
 ## Build errors
@@ -272,7 +271,7 @@ bundle DTS failed:
 
 For `js/ts` build errors, we can tell from the error message.
 
-- By `'bundle failed:'` to determine if the error is reported for a Bundle build or a Bundleless build?
-- What is the `format` of the build process?
-- What is the `target` of the build process?
-- The specific error message.
+- By `'bundle failed:'` to determine if the error is reported for a bundle build or a bundleless build
+- What is the `format` of the build process
+- What is the `target` of the build process
+- The specific error message

package/docs/en/guide/advance/in-depth-about-dev-command.md

@@ -21,7 +21,7 @@ In addition to the `dev` command, you can also start a debugging tool or task di
 If you need to extend the dev command, or rather provide your own Module Tools debugging tool plugin, then you will need to know the following first.
 
 * [Development of plugins](plugins/guide/getting-started)
-* [Debugging Tools Plugin API](/api/plugin-api/plugin-hooks#调试钩子)
+* [Debugging Tools Plugin API](/api/plugin-api/plugin-hooks#dev-hooks)
 
 In general, the code to implement a debugging tool that does nothing and the associated configuration is as follows.
 

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

@@ -90,7 +90,7 @@ In addition to the `"main"` attribute, the `"module"` attribute is usually set.
 
 > To learn more about how webpack does this, check out this [link](https://webpack.js.org/configuration/resolve/#resolvemainfields).
 
-### `"scripts"`
+### `scripts`
 
 The `"scripts"` attribute of the `package.json` file supports a number of built-in scripts and npm-preset lifecycle events, as well as arbitrary scripts.