@modern-js/module-tools-docs 2.0.1 → 2.0.3-beta.0

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

@@ -9,9 +9,9 @@ This chapter describes the configuration of the registered module-tools plugin.
 - type: `Array<ModuleToolsPlugin>`
 
 ```js modern.config.ts
-import { ExamplePlugin } from '. /plugins/example';
+import { examplePlugin } from '. /plugins/example';
 export default defineConfig({
-  plugins: [ExamplePlugin()],
+  plugins: [examplePlugin()],
 });
 ```
 

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

@@ -5,7 +5,8 @@ sidebar_position: 5
 # Testing
 
 This chapter describes the test-related configuration
-:::tips
+
+:::tip
 You need to enable the unit testing feature with `pnpm run new` first.
 :::
 

package/docs/en/api/plugin-api/plugin-hooks.md

@@ -56,7 +56,7 @@ type Return = BuildConfig;
 
 ### `beforeBuildTask`
 
-Based on the build configuration, module tools will split the overall build into multiple sub-build tasks. The Hook will be triggered before each build subtask.
+Based on the build configuration, Module Tools will split the overall build into multiple sub-build tasks. The Hook will be triggered before each build subtask.
 
 ``` ts
 export default (): CliPlugin<ModuleTools> => ({

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

@@ -4,7 +4,7 @@ sidebar_position: 6
 
 # Handle static resource files
 
-The module project will handle static resources used in the code. If configuration is required, then the [`buildConfig.asset`](/en/api/build-config#asset) API can be used.
+The module project will handle static resources used in the code. If configuration is required, then the [`buildConfig.asset`](/en/api/config/build-config#asset) API can be used.
 
 ## Default behavior
 
@@ -18,7 +18,6 @@ For the handling of static files, the module project currently supports the foll
 
 - Set the static resource path to `. /assets`.
 - For files over **10kb** they are inlined into the code.
-- Use [SVGR](https://react-svgr.com/) for files with the `.svg` suffix.
 
 Let us look at the following example:
 
@@ -144,6 +143,3 @@ If the size of `bg.png` is larger than 10 kb, then the product content will be.
 
 </CH.Spotlight>
 
-## SVGR
-
-WIP

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/build-config#autoexternal) and [`externals`](/en/api/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>
@@ -110,7 +110,7 @@ We know from the above example that when using the `autoExternal` and `externals
 - In a Node.js environment, you can get the react dependency with `require('react')`.
 - In a browser environment, you can get the react dependency via `global.react`.
 
-However, in the browser environment, when getting third-party dependencies, **global variable names are not necessarily identical to the dependency names**, so you have to use the [`buildConfig.umdGlobals`](/en/api/build-config#umdglobals) API.
+However, in the browser environment, when getting third-party dependencies, **global variable names are not necessarily identical to the dependency names**, so you have to use the [`buildConfig.umdGlobals`](/en/api/config/build-config#umdglobals) API.
 
 Again using the previous example, when the `react` dependency exists in the browser environment as a `windows.React` or `global.React` global variable, then:
 
@@ -164,7 +164,7 @@ console.info(React);
 
 At this point we will see the product code like this.
 
-```js dist/index.js focus=7:12
+```js dist/index.js focus=12:18
 (function (global, factory) {
   if (typeof module === 'object' && typeof module.exports === 'object')
     factory();
@@ -203,7 +203,7 @@ export default () => {
 
 ** By default, the name of the source file is used as the name of the module's global variable in the browser. **For the above example, the product would read as follows:
 
-```js ./dist/index.js focus=6:6
+```js ./dist/index.js focus=9:9
 (function (global, factory) {
   if (typeof module === 'object' && typeof module.exports === 'object')
     factory(exports);
@@ -218,7 +218,7 @@ export default () => {
 });
 ```
 
-If you need to modify it, you need to use the [`buildConfig.umdModuleName`](/en/api/build-config#umdmodulename) API.
+If you need to modify it, you need to use the [`buildConfig.umdModuleName`](/en/api/config/build-config#umdmodulename) API.
 
 When this API is used:
 
@@ -233,7 +233,7 @@ export default defineConfig({
 
 The construction products at this point are:
 
-```js ./dist/index.js focus=6:6
+```js ./dist/index.js focus=9:9
 (function (global, factory) {
   if (typeof module === 'object' && typeof module.exports === 'object')
     factory(exports);

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

@@ -8,10 +8,10 @@ The Module Project provides the Copy utility for copying already existing indivi
 
 ## Understanding the Copy API
 
-We can use the Copy tool via the [`buildConfig.copy`](/en/api/build-config#copy) API, which contains the following two main configurations.
+We can use the Copy tool via the [`buildConfig.copy`](/en/api/config/build-config#copy) API, which contains the following two main configurations.
 
-- [`patterns`](/en/api/build-config#copypatterns)
-- [`options`](/en/api/build-config#copyoptions)
+- [`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.
 
@@ -34,7 +34,7 @@ export default defineConfig({
 });
 ```
 
-`patterns.context` 一般和 `patterns.from` 配合使用，默认情况下它的值与 [`buildConfig.sourceDir`](/zh/api/build-config#sourcedir) 相同，因此我们可以按照如下方式指定 `src/data.json` 文件为要复制的文件：
+`patterns.context` 一般和 `patterns.from` 配合使用，默认情况下它的值与 [`buildConfig.sourceDir`](/api/config/build-config#sourcedir) 相同，因此我们可以按照如下方式指定 `src/data.json` 文件为要复制的文件：
 
 > 默认情况下，`buildConfig.sourceDir` 为 `src`
 
@@ -70,7 +70,7 @@ export default defineConfig({
 });
 ```
 
-`patterns.to` 用于指定复制文件的输出路径，默认情况下它的值为 [`buildConfig.outDir`](zh/api/build-config#outDir)对应的值。因此我们按照如下方式将 `src/index.html` 复制到 `dist` 目录下：
+`patterns.to` 用于指定复制文件的输出路径，默认情况下它的值为 [`buildConfig.outDir`](/api/config/build-config#outDir)对应的值。因此我们按照如下方式将 `src/index.html` 复制到 `dist` 目录下：
 
 ```ts
 export default defineConfig({

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

@@ -81,8 +81,8 @@ So how do you enable the packaging of third-party dependencies in your module pr
 
 The following APIs are provided in the build configuration to handle third-party dependencies:
 
-- [`buildConfig.autoExternal`](/en/api/build-config#autoexternal)
-- [`buildConfig.externals`](/en/api/build-config#externals)
+- [`buildConfig.autoExternal`](/en/api/config/build-config#autoexternal)
+- [`buildConfig.externals`](/en/api/config/build-config#externals)
 
 ### Turn off default behavior
 

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

@@ -9,8 +9,9 @@ In the [Basic Usage] section, we already knew that you can modify the output pro
 :::tip{title=notes}
 If you are not sure what `buildConfig` is, it is recommended to take some time to understand it by following this link.
 
-- [[modify-output-product](/en/guide/modify-output-product)]
-  :::
+- [[modify-output-product](/en/guide/basic/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.
 
@@ -24,17 +25,17 @@ A Bundle is a package of build products, which may be a single file or multiple
 
 Bundleless, on the other hand, means that each source file is compiled and built separately, but not packaged together. Each product 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**.
 
-In `buildConfig` you can specify whether the current build task is Bundle or Bundleless by using [`buildConfig.buildType`](/en/api/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`
 
-[`buildConfig.input`](/en/api/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.ts']`
 - When `buildType: 'bundleless'`, `input` defaults to `['src']`
   > In fact, at `buildType: 'bundle'`, the build tool detects the existence of a file matching the name rule `src/index.(j|t)sx?` and uses it as an entry file.
 
-:::warn{title=notes}
+:::warning{title=notes}
 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.
 :::
 
@@ -44,7 +45,7 @@ We know from the defaults: **Bundle builds can generally specify a file path as
 
 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 product outputs**. So for the following example, `. /src/index.ts` corresponds to the path of the build product file as `. /dist/main.js`.
 
-```tsx modern.config.ts
+```js modern.config.ts
 import { defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({
@@ -61,7 +62,7 @@ The Bundleless build process also supports such use, but it is not recommended.
 
 #### `sourceDir`
 
-[`sourceDir`](/en/api/build-config#sourcedir) is used to specify the source code directory, which is related to both.
+[`sourceDir`](/en/api/config/build-config#sourcedir) is used to specify the source code directory, which is related to both.
 
 - type file generation
 - [`outbase`](https://esbuild.github.io/api/#outbase) for specifying the build process
@@ -73,13 +74,13 @@ In general:
 
 ### Declaration Type Files
 
-The [`buildConfig.dts`](/en/api/build-config#dts) configuration is mainly used for type file generation.
+The [`buildConfig.dts`](/en/api/config/build-config#dts) configuration is mainly used for type file generation.
 
 #### Turn off type generation
 
 Type generation is turned on by default, if you need to turn it off, you can configure it as follows:
 
-```ts ./modern.config.ts
+```js modern.config.ts
 import { defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({
@@ -99,14 +100,14 @@ With `buildType: 'bundleless'`, type files are generated using the project's `ts
 
 The **module engineering solution also supports packaging of type files**, although care needs to be taken when using this feature.
 
-- Some third-party dependencies have incorrect syntax that can cause the packaging process to fail. So in this case, you need to exclude such third-party packages manually with [`buildConfig.externals`](/en/api/build-config#externals).
+- Some third-party dependencies have incorrect syntax that can cause the packaging process to fail. So in this case, you need to exclude such third-party packages manually with [`buildConfig.externals`](/en/api/config/build-config#externals).
 - It is not possible to handle the case where the type file of a third-party dependency points to a `.ts` file. For example, the `package.json` of a third-party dependency contains something like this: `{"types": ". /src/index.ts"}`.
 
 #### Alias Conversion
 
 During the Bundleless build process, if an alias appears in the source code, e.g.
 
-```ts ./src/index.ts
+```js ./src/index.ts
 import utils from '@common/utils';
 ```
 
@@ -123,7 +124,7 @@ However, there are some cases that cannot be handled at this time.
 
 General usage:
 
-```ts
+```js
 import { defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({
@@ -141,7 +142,7 @@ export default defineConfig({
 
 For the use of `dts.only`:
 
-```ts
+```js
 import { defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({
@@ -165,11 +166,11 @@ export default defineConfig({
 
 ### `buildConfig.define` Usage for different scenarios
 
-[`buildConfig.define`](/en/api/build-config#define) functions somewhat similar to [`webpack.DefinePlugin`](https://webpack.js.org/plugins/define-plugin/). A few usage scenarios are described here.
+[`buildConfig.define`](/en/api/config/build-config#define) functions somewhat similar to [`webpack.DefinePlugin`](https://webpack.js.org/plugins/define-plugin/). A few usage scenarios are described here.
 
 #### Environment variable replacement
 
-```ts
+```js
 import { defineConfig } from '@modern-js/module-tools';
 export default defineConfig({
   buildConfig: {
@@ -182,21 +183,21 @@ export default defineConfig({
 
 With the above configuration, we can put the following code.
 
-```
+```js
 // pre-compiler code
 console.log(process.env.VERSION);
 ```
 
 When executing `VERSION=1.0.0 modern build`, the conversion is:
 
-```
+```js
 // compiled code
 console.log('1.0.0');
 ```
 
 #### Global variable replacement
 
-```ts
+```js
 import { defineConfig } from '@modern-js/module-tools';
 export default defineConfig({
   buildConfig: {
@@ -209,14 +210,14 @@ export default defineConfig({
 
 With the above configuration, we can put the following code.
 
-```
+```js
 // pre-compile code
 console.log(VERSION);
 ```
 
 Convert to:
 
-```
+```js
 // post-compile code
 console.log('1.0.0');
 ```

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

@@ -9,8 +9,9 @@ sidebar_position: 2
 :::tip{title=注意}
 如果你还不清楚 `buildConfig` 是什么，建议花一些时间通过下面的链接了解一下：
 
-- 【[修改输出产物](/zh/guide/modify-output-product)】
-  :::
+- 【[修改输出产物](/guide/basic/modify-output-product)】
+
+:::
 
 而在本章里我们将要深入理解某些构建配置的使用以及了解执行 `modern build` 命令的时候发生了什么。
 

package/docs/en/guide/advance/theme-config.mdx

@@ -4,7 +4,7 @@ sidebar_position: 7
 
 # Theme Configuration
 
-The module project provides the ability to configure themes through the [`designSystem`](/en/api/design-system) API.
+The module project provides the ability to configure themes through the [`designSystem`](/en/api/config/design-system) API.
 
 ## Motivation and rationale
 
@@ -17,7 +17,7 @@ The so-called `designToken` corresponds to different things in different style d
   - `@apply` custom directive under css/less/sass to use a string with the same name as the HTML class name supported by tailwindcss.
 - css/less/scss: Generate global style variables via `designSystem`.
 
-The data structure of the `designSystem` API is borrowed from the [theme API](https://tailwindcss.com/docs/theme) in the `tailwindcss` configuration object, so a default set of `designToken` exists. For the default values, see the [`designSystem` API](/zh/api/design-system).
+The data structure of the `designSystem` API is borrowed from the [theme API](https://tailwindcss.com/docs/theme) in the `tailwindcss` configuration object, so a default set of `designToken` exists. For the default values, see the [`designSystem` API](/api/config/design-system).
 
 :::info
 The css/less/sass global variables are not supported yet.

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

@@ -6,7 +6,7 @@ sidebar_position: 1
 
 ## Environment preparation
 
-In order to use the Modern.js module engineering solution, you first need [NodeJS](https://nodejs.org/zh/) engine, we recommend the latest [LTS version](https://github.com/nodejs/Release), and make sure the Node version is **>=14.17.6**. because non-stable NodeJS releases frequently have bugs. You might consider installing via [nvm-windows](https://github.com/coreybutler/nvm-windows) and [nvm](https://github.com/nvm-sh/nvm) (Mac/linux), so you can easily switch to different NodeJS versions that might be required for different projects that you work on.
+In order to use the Modern.js module engineering solution, you first need [NodeJS](https://nodejs.org/zh/) engine, we recommend the latest [LTS version](https://github.com/nodejs/Release), and make sure the Node version is **>=14.18.0**. because non-stable NodeJS releases frequently have bugs. You might consider installing via [nvm-windows](https://github.com/coreybutler/nvm-windows) and [nvm](https://github.com/nvm-sh/nvm) (Mac/linux), so you can easily switch to different NodeJS versions that might be required for different projects that you work on.
 
 ## Getting Started with npm
 
@@ -14,7 +14,7 @@ Once NodeJS is installed, not only can you access the `node` executable from the
 
 Npm is the standard package manager for NodeJS. It started out as a tool for downloading and managing NodeJS package dependencies, but it has since evolved into a tool for front-end JavaScript.
 
-**If you already know something about usage of npm and npm packages, then you can directly see [npm package manager](/en/guide/before-getting-started#npm-package-manager) section.**
+**If you already know something about usage of npm and npm packages, then you can directly see [npm package manager](/en/guide/basic/before-getting-started#npm-package-manager) section.**
 
 ## npm package type project
 
@@ -71,6 +71,7 @@ Similarly, you can install **only packages needed for local development and test
 ```
 
 **When installing or using third-party npm packages be sure to determine what they are for and whether they should be placed in `"dependencies"` or `"devDependencies"` by distinguishing between their types.**
+
 :::tip
 In general, packages that need to be used in source code are `dependencies` dependencies. Unless you are exporting dependent code locally via packaging, in which case it can be treated as a `devDependencies` dependency.
 :::
@@ -161,25 +162,31 @@ npm install -g pnpm
 
 ## Module Tools configuration file
 
-A configuration file for Module Tools is provided in the initial module project directory -- `modern.config.(j|t)s`. By default, no configuration is required, so the `modern.config` configuration file is not required to exist.
+The Module Tools configuration file - `modern.config.(j|t)s` - is provided in the project directory of the module project created with `@modern-js/create`. However, the `modern.config` configuration file is not required to exist.
 
-The contents of the initial configuration file are as follows.
+By default, the contents of the generated configuration file are as follows.
 
 ```typescript
 // modern.config.ts
-import { defineConfig } from '@modern-js/module-tools';
+import moduleTools, { defineConfig } from '@modern-js/module-tools';
 
-export default defineConfig({});
+export default defineConfig({
+  plugins: [moduleTools()],
+  buildPreset: 'npm-library',
+});
 ```
 
 ```js
 // modern.config.js
-const { defineConfig } = require('@modern-js/module-tools');
+import moduleTools from '@modern-js/module-tools';
 
-module.exports = defineConfig({});
+export default {
+  plugins: [moduleTools()],
+  buildPreset: 'npm-library',
+};
 ```
 
-**We recommend using the `defineConfig` function**, but it is not mandatory to use it. So you can also return an object directly in the configuration file: the:
+**We recommend using the `defineConfig` function**, but it is not mandatory to use it. So you can also return an object directly in the config file: the
 
 ```typescript
 // modern.config.ts
@@ -188,5 +195,5 @@ export default {};
 
 ```js
 // modern.config.js
-module.exports = {};
+export default {};
 ```

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

@@ -26,7 +26,7 @@ Options:
 When you want to start a project build, you can execute the `modern build` command. When using this command, we can:
 
 - When wanting to start a build in watch mode, use the `--watch` option.
-- When you want to specify the path to the TypeScript configuration file read by the project build, use `-build --tsconfig . /path/config.json` option. This option overrides all [`buildConfig`](/zh/api/build-config) configurations in [`dts.tsconfigPath`](/zh/api/build-config).
+- When you want to specify the path to the TypeScript configuration file read by the project build, use `-build --tsconfig . /path/config.json` option. This option overrides all [`buildConfig`](/api/config/build-config) configurations in [`dts.tsconfigPath`](/api/config/build-config).
 - The `-no-dts` option can be used when the DTS type file generation and type checking behavior of the project needs to be turned off. **Note: The generation of type files depends on the results of type checking. If type checking is turned off, then type files will not be generated either**.
 - The `--no-clear` option can be used when the automatic clearing of the product output directory needs to be turned off.
 
@@ -55,11 +55,12 @@ The `modern new` command is used to start the microgenerator functionality, whic
 
 The following features can currently be enabled.
 
+- Testing support
 - Storybook debugging
 - Tailwind CSS support
 - Modern.js Runtime API
 
-You can learn more about these features in the [Using the micro generator](/zh/guide/use-micro-generator) section.
+You can learn more about these features in the [Using the micro generator](/guide/basic/use-micro-generator) section.
 
 ## `modern dev`
 
@@ -88,6 +89,7 @@ Options:
   -h, --help display help for command
 ```
 
+You need to execute `modern new` to turn on the test function before you can execute the `modern test` command.
 The `modern test` command will automatically run the `src/tests/*.test.(js|ts|jsx|tsx)` file as a test case.
 
 ## `modern lint`
@@ -204,5 +206,3 @@ Options:
 The `modern upgrade` command is used to upgrade the project Modern.js related dependencies to the latest version.
 
 Executing the command `npx modern upgrade` in the project root directory will update the Modern.js dependencies in `package.json` of the currently executing project to the latest version by default.
-
-command is provided in `@modern-js/module-tools` version **>= 1.17.0**, previous versions can be upgraded using `npx @modern-js/upgrade`.