@modern-js/module-tools-docs 2.0.0-beta.4

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

@@ -0,0 +1,125 @@
+# How to 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`.
+
+``` json pacakge.json
+{
+    "dependencies": {},
+    "devDependencies": {}
+}
+```
+
+Dependencies under `"dependencies"` are generally related to project code and builds, and if these third-party dependencies are declared under `"devDependencies"`, then there will be missing dependencies in production environments.
+
+In addition to `"dependencies"`, [`"peerDependencies"`](/en/guide/basic/before-getting-started#peerdependencies) can also declare dependencies that are needed in the production environment, but it puts more emphasis on the existence of these dependencies declared by `"peerDependencies"` in the project's runtime environment, similar to the plugin mechanism.
+
+## Default handling of third-party dependencies
+
+By default, third-party dependencies under `"dependencies"` and `"peerDependencies"` are not packaged in the module project**, so:
+
+<CH.Spotlight>
+
+```json ./v1/package.json
+{
+    "dependencies": {
+        "react": "^17"
+    },
+    // or
+    "peerDependencies": {
+        "react": "^17"
+    }
+}
+```
+
+---
+
+If the project has a dependency on `react`.
+
+```json ./v1/package.json
+{
+  "dependencies": {
+    "react": "^17"
+  },
+  // or
+  "peerDependencies": {
+      "react": "^17"
+  }
+}
+```
+
+---
+
+When a `react` dependency is used in the source code.
+
+``` tsx src/index.ts
+import React from "react";
+console.info(React);
+```
+
+---
+
+The `react` code is not packaged into the product at this point.
+
+``` js dist/index.js
+import React from "react";
+console.info(React);
+```
+
+</CH.Spotlight>
+
+## Packaging third-party dependencies
+
+However there are cases where you want to package these third-party dependencies into the product. The benefits of packaging third-party dependencies into the product are: **Reducing the time spent downloading third-party dependencies**.
+
+This way of handling third-party dependencies is generally more common in developing command-line tools, which can improve the loading speed of command-line tools and give users a better experience.
+
+So how do you enable the packaging of third-party dependencies in your module project?
+
+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)
+
+### Turn off default behavior
+
+When we want to turn off the default handling behavior for third-party dependencies, we can do so by:
+
+``` ts
+export default defineConfig({
+  buildConfig: {
+    autoExternal: false,
+  }
+});
+```
+
+This way the dependencies under `"dependencies"` and `"peerDependencies"` will be packaged. If you want to turn off the processing of only one of these dependencies, you can use the
+`buildConfig.autoExternal` in the form of an object.
+
+``` ts
+export default defineConfig({
+  buildConfig: {
+    autoExternal: {
+      dependencies: false,
+      peerDependencies: false,
+    },
+  }
+});
+```
+
+### Exclude specified third-party dependencies
+
+And in addition to the `buildConfig.autoExternal` API, `buildConfig.externals` can also control which third-party dependencies are to be handled. We can combine these two
+APIs to handle the project's dependencies in a more granular way.
+
+For example, when we need to leave only certain dependencies unpacked, we can configure it as follows.
+
+> In this case, it is likely that some dependencies are not suitable for packaging. If this is the case, then you can handle it as follows.
+
+``` ts
+epxort default defineConfig({
+  buildConfig: {
+    autoExternal: false,
+    externals: ['pkg-1', /pkg-2/],
+  }
+});
+```

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

@@ -0,0 +1,266 @@
+# In-depth understanding of build
+
+In the [Basic Usage] section, we already knew that you can modify the output product of a project through the `buildConfig` configuration. `buildConfig` not only describes some of the features of the product, but also provides some functionality for building the product.
+
+:::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)]
+:::
+
+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`
+
+### 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).
+
+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).
+
+### 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.
+
+* 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}
+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**.
+
+#### 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 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
+import { defineConfig } from '@modern-js/module-tools';
+
+export default defineConfig({
+    buildConfig: {
+        input: {
+            main: ['./src/index.ts'],
+        },
+        outdir: './dist',
+    },
+});
+```
+
+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.
+
+* type file generation
+* [`outbase`](https://esbuild.github.io/api/#outbase) for specifying the build process
+
+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.
+
+### Declaration Type Files
+
+The [`buildConfig.dts`](/en/api/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
+import { defineConfig } from '@modern-js/module-tools';
+
+export default defineConfig({
+  buildConfig: {
+    dts: false
+  }
+});
+```
+
+:::tip
+The build speed is generally improved by closing the type file.
+:::
+
+#### Build type files
+
+With `buildType: 'bundleless'`, type files are generated using the project's `tsc` command to complete production.
+
+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).
+* 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
+import utils from '@common/utils';
+```
+
+Normally, product type files generated with `tsc` will also contain these aliases. However, Module Tools will convert the aliases in the type file generated by `tsc` to:
+
+* 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.
+
+#### Some examples of the use of `dts`
+
+General usage:
+
+``` ts
+import { defineConfig } from '@modern-js/module-tools';
+
+export default defineConfig({
+  // The output path of the packaged type file at this point is `./dist/types`
+  buildConfig: {
+    buildType: 'bundle',
+    dts: {
+      tsconfigPath: './other-tsconfig.json',
+      distPath: './types',
+    },
+    outdir: './dist',
+  }
+});
+```
+For the use of `dts.only`:
+
+``` ts
+import { defineConfig } from '@modern-js/module-tools';
+
+export default defineConfig({
+  // At this moment the type file is not packaged and the output path is `./dist/types`
+  buildConfig: [
+    {
+      buildType: 'bundle',
+      dts: false,
+      outdir: './dist',
+    },
+    {
+      buildType: 'bundleless',
+      dts: {
+        only: true,
+      },
+      outdir: './dist/types',
+    }
+  ]
+});
+```
+
+### `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.
+
+#### Environment variable replacement
+
+``` ts
+import { defineConfig } from '@modern-js/module-tools';
+export default defineConfig({
+  buildConfig: {
+    define: {
+      'process.env.VERSION': JSON.stringify(process.env.VERSION || '0.0.0')
+    }
+  }
+});
+```
+
+With the above configuration, we can put the following code.
+
+```
+// pre-compiler code
+console.log(process.env.VERSION);
+```
+
+When executing ``VERSION=1.0.0 modern build``, the conversion is:
+
+```
+// compiled code
+console.log('1.0.0');
+```
+
+#### Global variable replacement
+
+``` ts
+import { defineConfig } from '@modern-js/module-tools';
+export default defineConfig({
+  buildConfig: {
+    define: {
+      'VERSION': JSON.stringify(require('. /package.json').version || '0.0.0')
+    }
+  }
+});
+```
+
+With the above configuration, we can put the following code.
+
+```
+// pre-compile code
+console.log(VERSION);
+```
+
+Convert to:
+
+```
+// post-compile code
+console.log('1.0.0');
+```
+
+Note, however: If the project is a TypeScript project, then you may need to add the following to the `.d.ts` file in the project source directory.
+> If the `.d.ts` file does not exist, then you can create it manually.
+
+``` ts env.d.ts
+declare const YOUR_ADD_GLOBAL_VAR;
+```
+
+## Build process
+
+When the `modern build` command is executed, the
+
+* Clear the products directory according to `buildConfig.outdir`.
+* Compile `js/ts` source code to generate the JS build product for Bundle/Bundleless.
+* Generate Bundle/Bundleless type files using `tsc`.
+* Handle Copy tasks.
+
+## Build errors
+
+When a build error occurs, based on the information learned above, it is easy to understand what error appears in the terminal.
+
+**Errors reported for js or ts builds:**
+
+``` bash
+error  ModuleBuildError:
+
+╭───────────────────────╮
+│ bundle failed:        │
+│  - format is "cjs"    │
+│  - target is "esnext" │
+╰───────────────────────╯
+
+Detailed Information:
+```
+
+**Errors reported for the type file generation process:**
+
+``` bash
+error   ModuleBuildError:
+
+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.

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

@@ -0,0 +1,22 @@
+# 深入理解构建
+
+在【基础使用】的部分，我们已经知道可以通过 `buildConfig` 配置对项目的输出产物进行修改。`buildConfig` 不仅描述了产物的一些特性，同时还为构建产物提供了一些功能。
+
+:::tip{title=注意}
+如果你还不清楚 `buildConfig` 是什么，建议花一些时间通过下面的链接了解一下：
+
+* 【[修改输出产物](/zh/guide/modify-output-product)】
+:::
+
+而在本章里我们将要深入理解某些构建配置的使用以及了解执行 `modern build` 命令的时候发生了什么。
+
+## 深入理解 `buildConfig`
+
+那么首先我们来理解 **bundle** 和 **bundleless** 的构建模式。
+
+### bundle 和 bundleless
+
+### input 与 sourceDir 的关系
+
+## 构建过程
+

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

@@ -0,0 +1,187 @@
+# Before you start
+
+## 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.
+## Getting Started with npm
+
+Once NodeJS is installed, not only can you access the `node` executable from the command line, but you can also execute the `npm` command.
+
+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.**
+
+## npm package type project
+
+So what is an npm package type project? When we execute the `npm init` command in an empty project directory, it creates a JSON file with the file name `package.json` under the current directory. During the creation process, we will need to fill in information including but not limited to the *name*, *version* *number*, *description*, etc. of the npm package, which will be found in the resulting `package.json` file as follows
+
+``` json
+{
+  "name": "npm-demo",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "",
+  "license": "ISC"
+}
+```
+
+At this point the project containing the initialized `package.json` file is an npm package type project, and you can execute the `npm publish` command to publish the project to the [npm Registry](https://www.npmjs.com/).
+
+The npm Registry is a [npm package store](https://docs.npmjs.com/about-the-public-npm-registry) where developers can not only publish their own npm packages to the npm Registry, but also use npm packages published by other developers through the npm Registry.
+
+A quality npm package will be used by more people because it not only saves a lot of code implementation work, but is also less likely to cause problems with the project.
+
+## Using third-party npm packages
+
+When adding a third-party npm package to an initial project, we can call this process "installing dependencies for the project" or "adding dependencies to the project". Before adding dependencies, we need to know one thing in particular -- **the types of packages npm depends on**.
+
+- `"dependencies"`: a type of package that your application will need in a production environment.
+- `"devDependencies"`: another type of package that is only needed for local development and testing.
+> packages can be understood as third-party npm packages.
+
+You can install the packages you need in a **production environment** by running `npm install npm-package-name` or `npm add npm-package-name`, or you can manually write the packages you need to install and the corresponding [semantic version](https://docs.npmjs.com/about-semantic-versioning) in `"dependencies"` in the `package.json` file, and run the `npm install` command to.
+
+``` json
+{
+    "name": "your-npm-project",
+    "dependencies": {
+      "npm-package-name": "0.1.0"
+    },
+}
+```
+
+Similarly, you can install **only packages needed for local development and testing** by running `npm install npm-package-name --save-dev` or `npm add npm-package-name --save-dev`, or you can manually write the packages to be installed and the corresponding [semantic version](https://docs.npmjs.com/about-semantic-versioning) in `"devDependencies"` in the `package.json` file, and run the `npm install` command as follows
+
+``` json
+{
+    "name": "your-npm-project",
+    "devDependencies": {
+      "npm-package-name": "0.1.0"
+    },
+}
+```
+
+**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.
+:::
+
+## Other npm bits and pieces to know
+
+### Program entry for npm packages
+
+There is a `"main"` attribute in `package.json` that corresponds to a module ID or, more intuitively, a NodeJS file path, which is the main entry point for your application.
+
+For example, if your package is named `foo` and the user installs it, and then executes the `require("foo")` code, then the file corresponding to the `"main"` field of the npm package `foo` will be exported.
+
+**It is recommended to set the `"main"` field in your npm package**. If `"main"` is not set, the default entry will be the `index.js` file in the root of the package.
+
+In addition to the `"main"` attribute, the `"module"` attribute is usually set. It is similar to the `"main"` attribute in that it is mainly used in webpack scenarios. webpack reads the npm package entry (file) in most cases in the order **"module" -> "main "**.
+
+> To learn more about how webpack does this, check out this [link](https://webpack.js.org/configuration/resolve/#resolvemainfields).
+
+### `"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.
+
+These can be executed by running `npm run-script <stage>` or simply `npm run <stage>`.
+
+Name matching [pre and post commands](https://docs.npmjs.com/cli/v9/using-npm/scripts#pre--post-scripts) will also be run (e.g. `premyscript`, `myscript`, `postmyscript` ).
+
+``` json
+{
+    "scripts": {
+        "premyscript": "",
+        "myscript": "",
+        "postmyscript": "",
+    }
+}
+```
+
+When `npm run myscripts` is executed, the script corresponding to `premyscripts` will be executed before it, and the script corresponding to `postmyscripts` will be executed after it.
+
+Script commands from dependencies can be run with `npm explore <pkg> -- npm run <stage>`.
+
+There are also special lifecycle scripts that occur only under certain circumstances. Here are a few that are usually necessary to know.
+
+#### `npm install`
+
+When you run `npm install -g <pkg-name>`, the following scripts will run.
+
+- `preinstall`
+- `install`
+- `postinstall`
+- `prepublish`
+- `preprepare`
+- `prepare`
+- `postprepare`
+
+If your package root has a `binding.gyp` file and you don't define an `install` or `preinstall` script, then npm will build with `node-gyp rebuild` as the default install command, using [node-gyp](https://github.com/nodejs/node-gyp).
+
+#### `npm publish`
+
+When publishing a project, executing this command will trigger the following script.
+
+- `prepublishOnly`
+- `prepack`
+- `prepare`
+- `postpack`
+- `publish`
+- `postpublish`
+
+When running in [`-dry-run`](https://docs.npmjs.com/cli/v7/commands/npm-publish#dry-run) mode, the script corresponding to `prepare` will not be executed.
+
+### peerDependencies
+
+In some cases, your npm project has a compatibility relationship with its host tool or library (e.g. a webpack plugin project and webpack), and your npm project does not want to use the host as a necessary dependency, which usually means that your project is probably a plugin for that host tool or library. Your npm project will have certain requirements for the version of the host package, as only the APIs required by the npm project will be exposed under a specific version.
+
+For more explanation of `peerDependencies`, you can learn about the different ways npm, pnpm, and Yarn handle it at the following links.
+
+- [npm's explanation of peerDependencies](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#peerdependencies)
+- [pnpm vs npm vs Yarn](https://pnpm.io/feature-comparison)
+
+## npm package manager
+
+In addition to the standard package manager like npm, the mainstream ones are **pnpm** and **Yarn**, both of which are good alternatives to npm cli.
+
+It is recommended to use [pnpm](https://pnpm.io/installation) to manage project dependencies, which can be installed as follows.
+
+```bash
+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 contents of the initial configuration file are as follows.
+
+``` typescript
+// modern.config.ts
+import { defineConfig } from '@modern-js/module-tools';
+
+export default defineConfig({});
+```
+
+``` js
+// modern.config.js
+const { defineConfig } = require('@modern-js/module-tools');
+
+module.exports = defineConfig({});
+```
+
+**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:
+
+``` typescript
+// modern.config.ts
+export default {};
+```
+
+``` js
+// modern.config.js
+module.exports = {};
+```