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

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

@@ -0,0 +1,187 @@
+# 开始之前
+
+## 环境准备
+
+为了使用 Modern.js 模块工程解决方案，首先需要 [NodeJS](https://nodejs.org/zh/)，我们推荐最新的[长期维护版本](https://github.com/nodejs/Release)，并确保 Node 版本大于等于 **14.17.6**。因为非稳定的 NodeJS 时常有一些 Bug，你可以使用 [nvm-windows](https://github.com/coreybutler/nvm-windows) 和 [nvm](https://github.com/nvm-sh/nvm)（Mac/linux）安装，这样你就可以方便地切换到不同的 NodeJS 版本，这些版本可能会用于不同的项目。
+## 初识 npm
+
+当 NodeJS 被安装后，你不仅可以在命令行中访问 `node` 可执行程序，同时你也可以执行 `npm` 命令。
+
+npm 是 NodeJS 的标准软件包管理器。它一开始的用途是用于下载和管理 NodeJS 包的依赖关系，但后来它逐渐变成为一个用于前端 JavaScript 的工具。
+
+**如果你已经对 npm 和 npm 包的使用方式有所了解，那么可以直接跳到[【npm 包管理器】](/zh/guide/before-getting-started#npm-包管理器)部分。**
+
+## npm 包类型项目
+
+那么什么是 npm 包类型的项目呢？当我们在一个空的项目目录下执行 `npm init` 命令的时候，它会在当前目录下面创建一个文件名为 `package.json` 的 JSON 文件。在创建过程中，我们需要填写包括但不限于 npm 包的名称、版本号、描述等等内容，这些填写的内容都会在生成的 `package.json` 文件中找到：
+
+``` json
+{
+  "name": "npm-demo",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "",
+  "license": "ISC"
+}
+```
+
+此时这个包含了初始化后的 `package.json` 文件的项目就是一个 npm 包类型的项目，你可以执行 `npm publish` 命令将这个项目发布到 [npm Registry](https://www.npmjs.com/)。
+
+npm Registry 是一个 [npm 包存储的地方](https://docs.npmjs.com/about-the-public-npm-registry)，开发者们不仅可以将他们自己的 npm 包发布到 npm Registry，还可以通过 npm Registry 使用其他开发者发布的 npm 包。
+
+优质的 npm 包会有更多的人去使用，因为它不仅节省了很多代码实现的工作，同时也不容易让项目出现问题。
+
+## 使用第三方 npm 包
+
+当要为初始化的项目增加第三方的 npm 包的时候，我们可以把这一过程叫做“为项目安装依赖”或是“为项目增加依赖”。在增加依赖之前，首先我们要特别了解一件事情 —— **npm 依赖的软件包类型**：
+
+- `"dependencies"`：一种是你的应用程序在生产环境中需要的软件包。
+- `"devDependencies"`：另一种是仅在本地开发和测试中需要的软件包。
+> 软件包可以理解为是第三方的 npm 包。
+
+你可以通过执行 `npm install npm-package-name` 或者 `npm add npm-package-name` 的方式来安装在**生产环境中需要的软件包**，或者也可以在 `package.json` 文件中手动的将需要安装的包和对应的[语义化版本](https://docs.npmjs.com/about-semantic-versioning)写在 `"dependencies"` 里，并执行 `npm install` 命令：
+
+``` json
+{
+    "name": "your-npm-project",
+    "dependencies": {
+      "npm-package-name": "0.1.0"
+    },
+}
+```
+
+同理，你也可以执行 `npm install npm-package-name --save-dev` 或 `npm add npm-package-name --save-dev` 的方式来安装**仅在本地开发和测试中需要的软件包**，或者也可以在 `package.json` 文件中手动的将需要安装的包和对应的[语义化版本](https://docs.npmjs.com/about-semantic-versioning)写在 `"devDependencies"` 里，并执行 `npm install` 命令：
+
+``` json
+{
+    "name": "your-npm-project",
+    "devDependencies": {
+      "npm-package-name": "0.1.0"
+    },
+}
+```
+
+**在安装或者使用第三方 npm 包的时候一定要确定它们的用途，以及通过区分它们的类型确定好它们应该放在 `"dependencies"` 还是 `"devDependencies"` 中。**
+:::tip
+一般来说，需要在源代码中使用到的包都属于 `dependencies` 依赖。除非你通过打包的方式将依赖的代码输出到本地，那么这种情况可以将它作为 `devDependencies` 依赖。
+:::
+
+## 还需要了解的 npm 零碎知识
+
+### npm 包的程序入口
+
+在 `package.json` 中存在一个 `"main"` 属性，它对应的值是一个模块 ID，或者更直观的说是一个 NodeJS 文件路径，它是你程序的主要入口。
+
+例如你的包名为 `foo`，并且用户安装了它，然后执行 `require("foo")` 代码，那么 `foo` 这个 npm 包的 `"main"` 字段对应的文件将会被导出。
+
+**推荐在你的 npm 包里一定要设置 `"main"` 字段**。如果没有设置 `"main"`，则默认入口为包的根目录下的 `index.js` 文件。
+
+除了需要设置 `"main"` 属性以外，一般还会设置 `"module"` 属性。它与 `"main"` 属性的用途类似，它主要是用于在 webpack 场景下使用。webpack 在大多数情况下，会以 **"module" -> "main"** 这个顺序读取 npm 包的入口（文件）。
+
+> 想要了解关于 webpack 如何做这件事，可以查看这个[链接](https://webpack.js.org/configuration/resolve/#resolvemainfields)。
+
+### `"scripts"`
+
+`package.json` 文件的 `"scripts"` 属性支持一些内置的脚本和 npm 预设的生命周期事件，以及任意的脚本。
+
+这些都可以通过运行 `npm run-script <stage>` 或简称 `npm run <stage>` 来执行。
+
+名称匹配的[前置命令和后置命令](https://docs.npmjs.com/cli/v9/using-npm/scripts#pre--post-scripts)也会被运行（例如 `premyscript`、`myscript`、`postmyscript`）。
+
+``` json
+{
+    "scripts": {
+        "premyscript": "",
+        "myscript": "",
+        "postmyscript": "",
+    }
+}
+```
+
+当执行 `npm run myscripts` 的时候，`premyscripts` 对应的脚本会在它之前执行，`postmyscripts` 对应的脚本会在它之后执行。
+
+来自依赖的脚本命令可以用 `npm explore <pkg> -- npm run <stage>` 运行。
+
+还有一些特殊的生命周期脚本（Life Scripts），只在某些情况下发生。这里介绍几个通常需要了解的情况。
+
+#### `npm install`
+
+当你运行 `npm install -g <pkg-name>` 时，以下脚本会运行。
+
+- `preinstall`
+- `install`
+- `postinstall`
+- `prepublish`
+- `preprepare`
+- `prepare`
+- `postprepare`
+
+如果你的软件包根目录有一个 `binding.gyp` 文件，而你没有定义 `install` 或 `preinstall` 脚本，那么 npm 将以 `node-gyp rebuild` 作为默认的 install 命令，使用 [node-gyp](https://github.com/nodejs/node-gyp) 进行编译。
+
+#### `npm publish`
+
+当发布项目的时候，执行该命令会触发以下脚本：
+
+- `prepublishOnly`
+- `prepack`
+- `prepare`
+- `postpack`
+- `publish`
+- `postpublish`
+
+当以 [`--dry-run`](https://docs.npmjs.com/cli/v7/commands/npm-publish#dry-run) 模式运行的时候，`prepare` 对应的脚本将不会执行。
+
+### peerDependencies
+
+在某些情况下，你的 npm 项目与它的宿主工具或者库之间存在某种兼容关系（例如一个 webpack 插件项目和 webpack），同时你的 npm 项目不想将宿主作为必要的依赖，这个时候通常说明你的项目可能是这个宿主工具或者库的插件。你的 npm 项目会对宿主包的版本有一定的要求，因为只有在特定的版本下才会暴露出 npm 项目所需要的 API。
+
+关于更多 `peerDependencies` 的解释，可以通过下面的链接了解 npm、pnpm、Yarn 对于它的不同处理方式：
+
+- [npm 对 peerDependencies 的解释](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#peerdependencies)
+- [pnpm vs npm VS Yarn](https://pnpm.io/feature-comparison)
+
+## npm 包管理器
+
+除了 npm 这种标准的包管理器以外，目前主流的还有 **pnpm** 和 **Yarn**，它们都是不错的 npm cli 替代品。
+
+推荐使用 [pnpm](https://pnpm.io/installation) 来管理项目依赖，可以通过下面的方式安装它：
+
+```bash
+npm install -g pnpm
+```
+
+## Module Tools 配置文件
+
+初始化的模块工程项目目录下提供了 Module Tools 的配置文件 —— `modern.config.(j|t)s`。默认情况下，不需要做任何配置，因此 `modern.config` 配置文件不是必须存在的。
+
+初始化的配置文件的内容如下：
+
+``` 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({});
+```
+
+**我们推荐使用 `defineConfig` 函数**，不过并不强制使用它。因此你也可以在配置文件中直接返回一个对象：
+
+``` typescript
+// modern.config.ts
+export default {};
+```
+
+``` js
+// modern.config.js
+module.exports = {};
+```

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

@@ -0,0 +1,204 @@
+# 命令预览
+
+模块工程项目可以使用的命令：
+
+## `modern build`
+
+``` bash
+Usage: modern build [options]
+
+构建模块命令
+
+Options:
+  -w, --watch            使用监听模式构建代码
+  --tsconfig [tsconfig]  指定 tsconfig.json 文件的路径 (default:
+                         "./tsconfig.json")
+  --platform [platform]  构建所有或者指定平台的产物
+  --no-dts               关闭 DTS 类型文件生成和类型检查
+  --no-clear             关闭自动清除产物输出目录的行为
+  -h, --help             展示当前命令的信息
+```
+
+当想要启动项目构建的时候，可以执行 `modern build` 命令。在使用这个命令的时候，我们可以：
+
+- 当想要以观察模式启动构建时，使用 `--watch` 选项。
+- 当想要指定项目编译读取的 TypeScript 配置文件的路径时，使用 `build --tsconfig ./path/config.json` 选项。使用该选项后，会覆盖所有 [`buildConfig`](/zh/api/build-config) 里 [`dts.tsconfigPath`](/zh/api/build-config) 配置。
+- 当需要关闭项目的 DTS 类型文件生成和类型检查行为时，可以使用 `--no-dts` 选项。**注意：类型文件的生成依赖类型检查的结果。如果关闭了类型检查，那么类型文件也不会生成**。
+- 当需要关闭自动清除产物输出目录的行为时，可以使用 `--no-clear` 选项。
+
+除了以上，模块工程还支持 `platform` 构建模式，可以用于执行其他工具的构建任务。例如，目前官方支持在安装了 `@modern-js/plugin-storybook` 插件后，可以通过执行 `modern build --platform` 或者 `modern build --platform storybook` 命令启动 Storybook 构建任务生成 Storybook 产物。
+
+:::tip{title=注意}
+在执行 Storybook 构建的时候，它需要读取项目的构建产物。因此**在执行 `modern build --platform` 命令启动 Storybook 构建的时候，要先执行一次 `modern build` 确保源码构建产物的存在**。
+:::
+
+## `modern new`
+
+``` bash
+Usage: modern new [options]
+
+模块化工程方案中执行生成器
+
+Options:
+  -d, --debug            开启 Debug 模式，打印调试日志信息 (default: false)
+  -c, --config <config>  生成器运行默认配置(JSON 字符串)
+  --dist-tag <tag>       生成器使用特殊的 npm Tag 版本
+  --registry             生成器运行过程中定制 npm Registry
+  -h, --help             display help for command
+```
+
+`modern new` 命令用于启动微生成器功能，它可以为项目启用默认没有提供的功能。
+
+目前可以开启的功能有：
+
+- Storybook 调试
+- Tailwind CSS 支持
+- Modern.js Runtime API
+
+关于这些功能，可以通过[【使用微生成器】](/zh/guide/use-micro-generator) 章节了解更多。
+
+## `modern dev`
+
+``` bash
+Usage: modern dev [options]
+
+本地开发命令
+
+Options:
+  -h, --help             display help for command
+
+Commands:
+[dev-tools-subCommand]
+```
+
+模块工程解决方案提供了使用调试工具的能力，可以通过 `modern dev` 命令来启动。不过要注意的是，默认情况下是没有提供调试相关的插件，因此此时执行 `modern dev` 会提示： *"No dev tools found available"*。
+
+目前官方支持的调试工具有 [Storybook](https://storybook.js.org/)，因此在你执行 `modern new` 命令开启它后，就可以执行 `modern dev` 或者 `modern dev storybook` 执行它。
+
+## `modern test`
+
+``` bash
+Usage: modern test [options]
+
+Options:
+  -h, --help  display help for command
+```
+`modern test` 命令会自动将 `src/tests/*.test.(js|ts|jsx|tsx)` 文件当做测试用例运行。
+
+
+## `modern lint`
+
+``` bash
+Usage: modern lint [options] [...files]
+
+lint and fix source files
+
+Options:
+  --no-fix    disable auto fix source file
+  -h, --help  display help for command
+```
+
+运行 [ESLint](https://eslint.org/) 检查代码语法情况。通常情况下，我们只需要在 `git commit` 阶段通过 [lint-staged](https://github.com/okonet/lint-staged) 检查本次提交修改的部分代码。
+
+- `--no-fix` 参数设置后可以关闭自动修复 lint 错误代码的能力。
+
+## `modern change`
+
+``` bash
+Usage: modern change [options]
+
+创建变更集
+
+Options:
+  --empty     创建空变更集 (default: false)
+  --open      使用编辑器中打开创建的变更集 (default: false)
+  -h, --help  display help for command
+```
+
+`modern change` 命令用于生成 [changesets](https://github.com/changesets/changesets) 需要的 Markdown 文件。
+
+## `modern pre`
+
+``` bash
+Usage: modern pre [options] <enter|exit> [tag]
+
+进入和退出预发布模式
+
+Options:
+  -h, --help  display help for command
+```
+
+可以使用 `modern pre` 命令在正式发布前[预发布](https://github.com/atlassian/changesets/blob/main/docs/prereleases.md)一个版本。
+
+## `modern bump`
+
+``` bash
+Usage: modern bump [options]
+
+使用变更集自动更新发布版本和变更日志
+
+Options:
+  --canary       创建一个预发布版本进行测试 (default: false)
+  --preid <tag>  在对预发布版本进行版本控制时指定标识符 (default: "next")
+  --snapshot     创建一个特殊版本进行测试 (default: false)
+  -h, --help     display help for command
+```
+
+按照 [changesets](https://github.com/changesets/changesets) 生成的变更记录的 Markdown 文件修改 `package.json` 中的版本号， 同时生成 `CHANGELOG.md` 文件。
+
+## `modern release`
+
+``` bash
+Usage: modern release [options]
+
+发布 npm 包
+
+Options:
+  --tag <tag>       发布 npm 包使用特定的 tag (default: "")
+  --ignore-scripts  发布时忽略 package.json 中的 scripts 命令，仅支持在 pnpm monorepo
+                    中使用 (default: "")
+  -h, --help        display help for command
+```
+
+`modern release` 命令可以将模块发布到 [npm Registry](https://www.npmjs.com/) 上。
+
+- `--tag` 参数可以指定发布时具体的 [dist tags](https://docs.npmjs.com/adding-dist-tags-to-packages)。
+
+## `modern gen-release-note`
+
+``` bash
+Usage: modern gen-release-note [options]
+
+根据当前仓库 changeset 信息生成 Release Note
+
+Options:
+  --repo <repo>      仓库名称，用于生成 Pull Request 链接， 例如： modern-js-dev/modern.js
+  --custom <cumtom>  自定义 Release Note 生成函数
+  -h, --help         display help for command
+```
+
+根据当前仓库的 changeset 信息自动生成 [Release Note](https://en.wikipedia.org/wiki/Release_notes)。
+
+:::tip{title=注意}
+需要在 `bump` 命令之前执行。
+:::
+
+## `modern upgrade`
+
+``` bash
+Usage: modern upgrade [options]
+
+升级 Modern.js 到最新版本
+
+Options:
+  --registry <registry>  定制 npm registry (default: "")
+  -d,--debug             开启 Debug 模式，打印调试日志信息 (default: false)
+  --cwd <cwd>            项目路径 (default: "")
+  -h, --help             display help for command
+```
+
+`modern upgrade` 命令，用于升级项目 Modern.js 相关依赖至最新版本。
+
+在项目根目录下执行命令 `npx modern upgrade`，会默认将当前执行命令项目的 `package.json` 中的 Modern.js 相关依赖更新至最新版本。
+
+命令在 `@modern-js/module-tools` 版本 **>= 1.17.0** 提供，之前版本可使用 `npx @modern-js/upgrade` 进行升级。

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

@@ -0,0 +1,144 @@
+# 修改输出产物
+
+## 默认输出产物
+
+当在初始化的项目里使用 `modern build` 命令的时候，会根据 Module Tools 默认支持的配置生成相应的产物。默认支持的配置具体如下：
+
+``` typescript
+import { defineConfig } from '@modern-js/module-tools';
+
+export default defineConfig({
+  buildPreset: 'base-config',
+});
+```
+
+**默认生成产物具有以下特点**：
+
+- 代码格式为 [CommonJS](https://nodejs.org/api/modules.html#modules-commonjs-modules)，或者简称为 `cjs`。
+- 代码语法支持到 `ES6`。
+- 所有的代码经过打包变成了一个文件，即进行了 **bundle** 处理。
+- 产物输出根目录为项目下的 `dist` 目录，类型文件输出的目录为 `dist/types`。
+
+:::tip
+1. 所谓“代码语法支持到 ES6”的意思是指：产物代码所支持的语法不会超过 `ES6`。如果源码中使用语法是 `ES6` 以上的语法（例如 `ES2017`），则会被进行转换。
+:::
+
+看到这里你可能会有以下疑问：
+
+1. `buildPreset` 是什么？
+2. 产物的这些特点是由什么决定的？
+
+那么接下来首先解释一下 `buildPreset`。
+
+## 构建预设
+
+`buildPreset` 代表着提前准备好的一组或者多组构建相关的配置，只需要使用 `buildPreset` 对应的预设值，就可以省去麻烦且复杂的配置工作，得到符合预期的产物。
+
+### 构建预设的字符串形式
+
+**构建预设的值可以是字符串形式**，因此这样形式的构建预设叫做预设字符串。
+
+模块工程解决方案根据 npm 包使用的通用场景，提供了通用的构建预设字符串以及相应的变体。目前支持的所有预设字符串可以通过 [BuildPreset API](/zh/api/build-config) 查看。这里讲解一下关于**通用的预设字符串与变体之间的关系**。
+
+在通用的预设字符串中，`"npm-library"` 可以用于在开发库类型的 npm 包的场景下使用，它适合大多数普通的模块类型项目。当设置 `"npm-library"` 的时候，项目的输出产物会有以下特点：
+
+- 在 `dist/lib` 目录下会得到代码格式为 `cjs`、语法支持到 `es6` 且经过打包处理后的产物。
+- 在 `dist/es` 目录下会得到代码格式为 `esm`、语法支持为 `es6` 且经过打包处理后的产物。
+- 在 `dist/types` 目录下会得到类型文件。如果不是 TypeScript 项目，则没有该目录。
+
+而预设字符串 `"npm-library"` 对应的变体则是在原本产物的基础上修改了**代码语法支持**这一特点，同时在字符串命名上也变为了 `"npm-library-[es5 | es2016...es2020 | esnext]"` 这样的形式。
+
+例如，如果在预设字符串 `"npm-library"` 对应的输出产物基础上，让产物代码支持的语法变为 `es2017` 的话，那么只需要将 `"npm-library"` 改变为 `"npm-library-es2017"` 就可以了。
+
+### 构建预设的函数形式
+
+**除了字符串形式以外，构建预设的值也可以是函数形式，在函数中可以打印或者修改某个预设值对应的具体配置**。
+
+例如，如果使用预设函数的形式达到预设字符串 `"npm-library-es2017"` 同样的效果，可以按照如下的方式：
+
+``` typescript
+import { defineConfig } from "@modern-js/module-tools";
+
+export default defineConfig({
+  buildPreset({ preset }) {
+    return preset.NPM_LIBRARY.map(config => {
+      return { ...config, target: 'es2017' };
+    });
+  },
+});
+```
+
+在上面的代码实现中，`preset.NPM_LIBRARY` 与预设字符串 `"npm-library"` 是相对应的，它代表着 `"npm-library"` 等价的多组构建相关的配置。我们通过 `map` 方法遍历了 `NPM_LIBRARY` 这个数组，在这个数组中包含了多个 `buildConfig` 对象。我们将原本的 `buildConfig` 对象进行了浅拷贝并修改了浅拷贝后得到 `buildConfig.target`，将它指定为 `es2017`。
+> 关于 `preset.NPM_LIBRARY` 具体对应的值，可以通过 [BuildPreset API](/zh/api/build-config) 查看。在 `preset` 对象下不仅包含了 `NPM_LIBRARY`，还包含了其他类似的常量。
+
+那么这里的 `buildConfig` 对象是什么呢？之前提到的构建产物特点又是根据什么呢？
+
+接下来我们解释一下。
+
+## 构建配置（对象）
+
+**`buildConfig` 是一个用来描述如何编译、生成构建产物的配置对象**。在最开始提到的关于“*构建产物的特点*”，其实都是 `buildConfig` 所支持的属性。目前所支持的属性覆盖了大部分模块类型项目在构建产物时的需求，`buildConfig` 不仅包含一些产物所具备的属性，也包含了构建产物所需要的一些特性功能。接下来从分类的角度简单罗列一下：
+
+**构建产物的基本属性包括：**
+
+- 产物是否被打包：对应的 API 是 [`buildConfig.buildType`](/zh/api/build-config#buildtype)。
+- 产物对于语法的支持：对应的 API 是 [`buildConfig.target`](/zh/api/build-config#target)。
+- 产物格式：对应的 API 是 [`buildConfig.format`](/zh/api/build-config#format)。
+- 产物类型文件如何处理，对应的 API 是 [`buildConfig.dts`](/zh/api/build-config#dts)。
+- 产物的 sourceMap 如何处理：对应的 API 是 [`buildConfig.sourceMap`](/zh/api/build-config#sourcemap)。
+- 产物对应的输入（或者是源文件）：对应的 API 是 [`buildConfig.input`](/zh/api/build-config#input)。
+- 产物输出的目录：对应的 API 是 [`buildConfig.outdir`](/zh/api/build-config#outdir)。
+- 构建的源码目录：对应的 API 是 [`buildConfig.sourceDir`](/zh/api/build-config#sourcedir)。
+
+**构建产物所需的常用功能包括：**
+
+- 别名：对应的 API 是 [`buildConfig.alias`](/zh/api/build-config#alias)。
+- 静态资源处理：对应的 API 是 [`buildConfig.asset`](/zh/api/build-config#asset)。
+- 第三方依赖处理：对应的 API 有：
+  * [`buildConfig.autoExternal`](/zh/api/build-config#autoexternal)。
+  * [`buildConfig.externals`](/zh/api/build-config#externals)。
+- 拷贝：对应的 API 是 [`buildConfig.copy`](/zh/api/build-config#copy)。
+- 全局变量替换：对应的 API 是 [`buildConfig.define`](/zh/api/build-config#define)。
+- 指定 [JSX](https://reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html) 编译方式，对应的 API 是 [`buildConfig.jsx`](/zh/api/build-config#jsx)。
+
+**一些高级属性或者使用频率不高的功能：**
+
+- 产物代码压缩：对应的 API 是 [`buildConfig.minify`](/zh/api/build-config#minify)。
+- 代码分割：[`buildConfig.spitting`](/zh/api/build-config#splitting)
+- 指定构建产物用于 NodeJS 环境还是浏览器环境：对应的 API 是 [`buildConfig.platform`](/zh/api/build-config#platform)。
+- umd 产物相关：
+  * 指定 umd 产物外部导入的全局变量：对应的 API 是 [`buildConfig.umdGlobals`](/zh/api/build-config#umdglobals)。
+  * 指定 umd 产物的模块名：对应的 API 是 [`buildConfig.umdModuleName`](/zh/api/build-config#umdmodulename)。
+
+除了以上分类以外，关于这些 API 的常见问题和最佳实践可以通过下面的链接来了解，敬请期待。
+* [什么是 `bundle` 和 `bundleless`?](/zh/guide/advance/in-depth-about-build#bundle-和-bundleless)
+* [`input` 与 `sourceDir` 的关系](/zh/guide/advance/in-depth-about-build#input-与-sourcedir-的关系)。
+* [产物中类型文件的多种生成方式](/zh/guide/advance/in-depth-about-build#类型文件)。
+* [`buildConfig.define` 不同场景的使用方式。](/zh/guide/advance/in-depth-about-build#buildconfigdefine-不同场景的使用方式)
+* [如何处理第三方依赖？](/zh/guide/advance/external-dependency)
+* [如何使用拷贝？](/zh/guide/advance/copy)
+* [如何构建 umd 产物？](/zh/guide/advance/build-umd#设置项目的全局变量名称)
+* [静态资源目前所支持的能力。](/zh/guide/advance/asset)
+
+## 什么时候使用 `buildConfig`
+
+`buildConfig` 是用于修改产物的方式之一，**当与 `buildPreset` 配置同时存在的时候，只有 `buildConfig` 才会生效**。因此如果按照如下方式配置：
+
+``` typescript
+import { defineConfig } from '@modern-js/module-tools';
+
+export default defineConfig({
+  buildConfig: [{}],
+  buildPreset: 'base-config',
+});
+```
+
+那么此时就会看到如下提示：
+
+``` bash
+因为同时出现 'buildConfig' 和 'buildPreset' 配置，因此仅 'buildConfig' 配置生效
+```
+
+`buildPreset` 代表的一组或者多组构建相关的配置都是由 `buildConfig` 组成，**当使用 `buildPreset` 无法满足当前项目需求的时候，就可以使用 `buildConfig` 来自定义输出产物**。
+
+在使用 `buildConfig` 的过程，就是对“*获得怎样的构建产物*”的思考过程。

package/docs/zh/guide/basic/publish-your-project.md

@@ -0,0 +1,112 @@
+# 版本管理与发布
+
+一个 npm 类型的模块项目发布流程包含了两个阶段：
+
+* 第一阶段是在开发期间，开发者需要提供一个变更文件来记录需要发布的变动；
+* 第二阶段是在发布期间，Module Tools 可以收集所有的变更文件来更新版本、更新发布日志，并发布新的包到 [npm Registry](https://www.npmjs.com/) 上。
+
+## 跟踪变更
+
+**当项目发生变化的时候需要将变化的内容记录下来**。项目发生的变化一般是指：
+
+* 新功能
+* 修复问题
+* 配置文件修改
+* ...
+
+当这些变化一旦完成后，需要通过以下命令来对当前的变化进行记录：
+
+* [`modern change`](/zh/guide/command-preview#modern-change)
+
+执行 `modern change` 命令后会向开发者提出几个问题，并根据开发者的回答生成变更记录。变更记录文件包含了版本变化的类型和其描述，该文件会被提交到 git 仓库中。
+
+``` bash
+$ npx modern change
+🦋  What kind of change is this for module-example? (current version is 0.1.0) · patch
+🦋  Please enter a summary for this change (this will be in the changelogs). Submit empty line to open external editor
+🦋  Summary · publish test
+🦋  === Releasing the following packages ===
+🦋  [Patch]
+🦋    module
+🦋  Is this your desired changeset? (Y/n) · true
+🦋  Changeset added! - you can now commit it
+🦋
+🦋  If you want to modify or expand on the changeset summary, you can find it here
+🦋  info /xxxxxx/module/.changeset/brave-dryers-agree.md
+```
+
+当执行成功后，生成的包含变更记录的 Markdown 文件会保存在项目的 `.changeset` 目录下面。其内容类似下面这样：
+
+``` markdown .changeset/brave-dryers-agree.md
+---
+"module-example": patch
+---
+
+publish test
+```
+
+## 版本更新
+
+当需要更新项目版本的时候，执行以下命令：
+
+* [`modern bump`](/zh/guide/command-preview#modern-bump)
+
+执行 `modern bump` 将会基于 `.changeset/` 目录下记录了变更的 Markdown 文件内容来修改 `package.json` 中的版本号，同时生成 `CHANGELOG.md` 文件。**而当版本更新完成后，这些记录变更的 Markdown 文件也会被删除，也可说这些 Markdown 文件被“消耗”掉了**。
+
+``` markdown CHANGELOG.md
+# module
+
+## 0.1.1
+### Patch Changes
+
+- publish test
+```
+
+## 发布
+
+发布项目可以执行以下命令：
+
+* [`modern publish`](/zh/guide/command-preview#modern-release)
+
+`modern release` 命令可以将项目发布到 npm Registry。
+
+此时发布的是 `latest` 版本，也可以说是正式版本。如果想要修改 `dist-tag`，可以通过 `modern release --tag` 命令来指定。例如：
+
+``` bash
+modern release --tag beta
+```
+
+但是如果希望将当前项目的版本号也修改为预发布的版本号，则需要使用 `modern pre` 命令。
+
+> 所谓 `dist-tag`，可以理解：为当前发布的版本打标签。一般来说，默认发布的版本对应的 `dist-tag` 为 `latest`，因此可以把 `latest` 认为是正式版本的 `dist-tag`。
+
+## 预发布
+
+当需要在正式发布之前进行预发布，则需要执行以下命令：
+
+* [`modern pre`](/zh/guide/command-preview#modern-pre)
+
+首先 `modern pre enter <tag>` 进入预发布模式，`<tag>` 可以与发布项目的时候使用 `modern release --tag` 命令指定的 `tag` 一致。
+
+``` bash
+$ npx modern pre enter next
+🦋  success Entered pre mode with tag next
+🦋  info Run `changeset version` to version packages with prerelease versions
+✨  Done in 5.30s.
+```
+
+接着可以使用 `modern bump` 命令更新具体的版本号，**此时不会真正的“消耗”记录变更的 Markdown 文件**：
+
+``` bash
+$ npx modern bump
+🦋  warn ===============================IMPORTANT!===============================
+🦋  warn You are in prerelease mode
+🦋  warn If you meant to do a normal release you should revert these changes and run `changeset pre exit`
+🦋  warn You can then run `changeset version` again to do a normal release
+🦋  warn ----------------------------------------------------------------------
+🦋  All files have been updated. Review them and commit at your leisure
+```
+
+然后可以看到 `package.json` 中更新的版本号会类似这样：`0.1.2-next.0`。
+
+最后，**如果不需要再进行预发布，则一定要执行 `modern pre exit` 命令**，这样可以退出预发布状态，并且当再次执行 `modern bump` 命令的时候，就可以发布正式的版本。