@modern-js/main-doc 0.0.0-next-20221116121040

package/zh/guides/topic-detail/changesets/release.md

@@ -0,0 +1,228 @@
+---
+sidebar_position: 3
+---
+
+# 发布正式版本
+
+发版正式版本时，我们需要根据开发过程中生成的 changeset 进行相关包版本号升级，并执行 publish 命令发布到 NPM 上。
+
+## 步骤
+
+:::info
+以下示例命令都以 pnpm 作为包管理工具进行，如果需要使用其他包管理工具，请按需求进行替换。
+:::
+
+### 模块工程方案
+
+#### 在根目录执行以下命令：
+
+```bash
+pnpm run bump
+```
+
+![执行 bump 命令](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-module-bump.png)
+
+执行该命令时，changeset 会自动进行以下操作：
+
+- 删除 `.changesets` 目录下的所有 changeset 文件。
+
+- 根据 changeset 信息升级该包版本号。
+
+- 在根目录的 `CHANGELOG.md` 文件中写入 Changelog 信息，文件不存在时会自动创建。
+
+#### 确认并提交当前变更：
+
+```bash
+git add .
+git commit -m "release: bump package"
+```
+
+#### 在根目录执行以下命令发布包至 NPM：
+
+```bash
+pnpm run release
+```
+
+![执行 release 命令](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-module-release.png)
+
+#### push 对应的 tag 信息至远程仓库：
+
+```bash
+git push --follow-tags
+```
+
+### Monorepo 工程方案
+
+#### 在根目录执行以下命令：
+
+```bash
+pnpm run bump
+```
+
+![执行 bump 命令](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-monorepo-bump.png)
+
+执行该命令时，changeset 会自动进行以下操作：
+
+- 删除 `.changesets` 目录下的所有 changeset 文件。
+
+- 根据 changeset 信息升级相关包的版本号，除了显示写入 changeset 的包，执行命令时还会将 Monorepo 中所有的包进行依赖关系分析，如果需要升级，也会对应的自动升级版本号。
+
+- 在需要升级的包目录的 `CHANGELOG.md` 文件中写入 Changelog 信息，文件不存在时会自动创建。
+
+#### 确认并提交当前变更：
+
+:::info
+需确认自动升级的版本号是否符合预期，如果需要了解版本升级策略，请查看[升级版本策略](/docs/guides/topic-detail/changesets/release#升级版本策略)。
+:::
+
+```bash
+git add .
+git commit -m "release: bump package"
+```
+
+#### 在根目录执行以下命令发布包至 NPM：
+
+```bash
+pnpm run release
+```
+
+执行该命令时，将会依次判断 Monorepo 中所有的 packages 的版本是否在 NPM 中存在，如果不存在将会执行 `publish` 命令发布。
+
+:::warning
+当 Monorepo 中包之间依赖关系使用 workspace 声明时，注意不要直接在 package 对应的子目录直接执行 `npm publish` 发布 package，使用 `relesae` 命令在发布时将会自动去除 workspace 声明，确保 NPM 包发布之后可用。
+:::
+
+#### push 对应的 tag 信息至远程仓库：
+
+```bash
+git push --follow-tags
+```
+
+## 参数
+
+### bump 命令参数
+
+- `--snapshot` 生成基于时间戳的版本号。
+
+```bash
+pnpm run bump -- --snapshot canary
+```
+
+执行完成后，对应的升级版本号将会变成 `0.0.0-canary-20220622092823` 的形式，其中 canary 为 snapshot 配置的标记，如果不配置，将直接生成 `0.0.0-20220622092823` 的形式。
+
+该参数主要用于发布临时测试版本进行测试，不需要进行代码提交。
+
+- `--ignore` 发布时手动忽略部分包。
+
+例如本次发布你需要忽略 `module-2` 包：
+
+```bash
+pnpm run bump -- --ignore module-2
+```
+
+命令执行完成后，将会忽略 `module-2` 包的更新。注意如果存在包依赖 `module-2`，需要将对应包也加入到 `ignore` 参数中，否则 `bump` 命令将执行失败。
+
+加入多个包的使用姿势为：
+
+```bash
+pnpm run bump -- --ignore module-2 --ignore module-3
+```
+
+### release 命令参数
+
+- `--otp` 使用 `npm token` 执行 relesae 命令发布对应包
+
+```bash
+pnpm run relese -- --otp <token>
+```
+
+- `--tag` 本地发布使用特定的 tag，默认使用 `latest`
+
+```bash
+pnpm run release -- --tag <tag>
+```
+
+- `--ignore-scripts` 发布时忽略 npm scripts。
+
+执行 `publish` 命令时，npm 会自动触发很多命令，比如 `prepare`、`prepublish`，使用该参数可以忽略这些命令执行。该参数仅支持在使用 pnpm 的 Monorepo 中使用。
+
+```bash
+pnpm run release -- --ignore-scripts
+```
+
+- `--no-git-checks` 发布时忽略检查当前分支。
+
+执行发布命令时，默认会自动检查当前分支是否为发布分支，是否存在未提交变更等等，使用该参数可以忽略 git 相关检查。
+
+```bash
+pnpm run release -- --no-git-checks
+```
+
+## 升级版本策略
+
+### dependencies 或者 devDependencies 依赖
+
+#### patch 版本依赖只升级自身
+
+例如存在如下场景：
+
+Monorepo 中存在两个包，`module-1` 和 `module-2`，`module-2` 的 `dependencies` 中存在 `module-1`。
+
+当前存在的 changeset 为 `module-1` 的 `patch` 版本升级。
+
+执行 bump 命令后将只会升级 `module-1` 的 patch 版本号。
+
+#### major / minor 版本自身升级 major 或者 minor 版本号，依赖包升级 patch 版本号
+
+例如存在如下场景：
+
+Monorepo 中存在两个包，`module-1` 和 `module-2`，`module-2` 的 dependencies 中存在`module-1`。
+
+当前存在的 changeset 为 `module-1` 的 minor 版本升级。
+
+执行 bump 命令后 `module-1` 会升级 `minor` 版本号，`module -2` 会升级 `patch` 版本号。
+
+### peerDependencies 依赖
+
+#### patch 版本依赖自身和依赖包都升级 patch 版本号
+
+例如存在如下场景：
+
+Monorepo 中存在两个包，`module-1` 和 `module-2`，`module-2` 的 `peerDependencies` 中存在 `module-1`。
+
+当前存在的 changeset 为 `module-1` 的 patch 版本升级。
+
+执行 bump 命令后将 `module-1` 和 `module-2` 都升级 patch 版本号。
+
+#### major / minor 版本自身升级 major 或者 minor 版本号，依赖包升级 major 版本号
+
+例如存在如下场景：
+
+Monorepo 中存在两个包，`module-1` 和 `module-2`，`module-2` 的 `peerDependencies` 中存在 `module-1`。
+
+当前存在的 changeset 为 `module-1` 的 `minor` 版本升级。
+
+执行 bump 命令后将 module-1 将升级 `minor` 版本号， `module-2` 升级 `major` 版本号。
+
+#### 修改 peerDependencies 的升级策略
+
+`peerDependencies` 的升级策略支持通过配置 `onlyUpdatePeerDependentsWhenOutOfRange` 来修改依赖升级策略，当只有超出声明的版本类型范围时，才对应升级 `peerDependencies`。
+
+```json
+{
+  "___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH": {
+    "onlyUpdatePeerDependentsWhenOutOfRange": true
+  },
+  ...
+}
+```
+
+例如存在如下场景：
+
+Monorepo 中存在两个包，`module-1` 和 `module-2`，`module-2` 的 `peerDependencies` 中存在 `module-1`，声明 `module-1` 的版本号使用 `^`。
+
+当前存在的 changeset 为 `module-1` 的 `patch` 或者 `minor` 版本升级。
+
+执行 `bump` 命令后只升级 `module-1` 版本号。
+
+需注意，如果包版本号在 `0.x.x` 的范围时，`minor` 版本号升级也是超出声明的版本类型范围的。

package/zh/guides/topic-detail/compile-speed.md

@@ -0,0 +1,182 @@
+---
+title: 提升编译速度
+sidebar_position: 9
+---
+
+Modern.js 默认内置了一系列的编译性能优化策略，但是随着业务场景变复杂、仓库的代码量增大，在使用过程中可能会遇到一些编译性能的问题。
+
+本文档提供了一些可选的提速策略，**开发者可以根据实际场景选取其中的部分策略**，从而进一步提升编译速度。
+
+## 通用优化策略
+
+以下是一些通用的优化策略，对 `modern dev` 和 `modern build` 均有提速效果，其中部分策略对包体积也有优化。
+
+### 减少重复依赖
+
+在实际项目中，会存在某些第三方依赖被安装了多个版本的现象。重复依赖会导致包体积变大、编译速度变慢。
+
+我们可以通过社区中的一些工具来自动消除重复依赖，比如 [yarn-deduplicate](https://github.com/scinos/yarn-deduplicate)。
+
+```bash
+npx yarn-deduplicate && yarn
+```
+
+如果你在使用 `pnpm`，可以考虑通过**重新生成 lock 文件**来减少重复依赖，
+
+```bash
+rm -rf ./node_modules pnpm-lock.yaml && pnpm install
+```
+
+:::info
+删除 lock 文件会使项目中的依赖版本自动升级到指定范围下的最新版，请进行充分的测试。
+:::
+
+### 替换体积较大的依赖
+
+建议将项目中体积较大的第三方依赖替换为更轻量的库，比如将 [moment](https://momentjs.com/) 替换为 [day.js](https://day.js.org/)。
+
+如果不清楚项目中哪些三方依赖的体积较大，可以在执行构建时添加 `--analyze` 参数：
+
+```bash
+npx modern build --analyze
+```
+
+该参数会生成一个分析构建产物体积的 HTML 文件，手动在浏览器中打开该文件，可以看到打包产物的瓦片图。区块的面积越大，说明该模块的体积越大。
+
+<img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/mwa-build-analyze-8784f762c1ab0cb20935829d5f912c4c.png" />
+
+### 避免使用 ts-loader
+
+默认情况下，Modern.js 使用 Babel 编译 TS 文件，开启 `output.enableTsLoader` 选项后，会使用 `ts-loader` 编译 TS 文件。
+
+由于 `ts-loader` 需要进行额外的语法解析和类型检查，因此会导致项目编译速度变慢，请避免使用。
+
+```js title="modern.config.js"
+export default defineConfig({
+  output: {
+    // 移除这项配置
+    enableTsLoader: true,
+  },
+});
+```
+
+详见 [tools.tsLoader 文档](/docs/configure/app/tools/ts-loader)。
+
+### 提升 Browserslist 范围
+
+**减少 Polyfill 的代码量可以提升编译速度。**Modern.js 会根据项目的 Browserslist 配置范围进行代码编译，并注入相应的 Polyfill。如果项目对兼容性的要求较低，可以根据实际情况，提升 Browserslist 范围，从而减少 Polyfill 的代码量。
+
+默认的 Browserslist 配置为：
+
+```js
+['> 0.01%', 'not dead', 'not op_mini all'];
+```
+
+比如只兼容 Chrome 53 以上的浏览器，可以改成：
+
+```js
+['Chrome >= 53'];
+```
+
+详见 [客户端兼容性 - Browserslist 配置](/docs/guides/advanced-features/compatibility#browserslist-配置)。
+
+### 按需引入 Polyfill
+
+明确第三方依赖不需要 Polyfill 的情况下，可以将 `output.polyfill` 设置为 `usage`，根据代码中使用到的语法，按需注入所需的 Polyfill 代码，从而减少 Polyfill 的代码量。
+
+```js title="modern.config.js"
+export default defineConfig({
+  output: {
+    polyfill: 'usage',
+  },
+});
+```
+
+详见 [客户端兼容性 - Polyfill 模式](/docs/guides/advanced-features/compatibility#polyfill-模式)。
+
+## dev 优化策略
+
+以下是针对 `modern dev` 进行提速的策略。
+
+### 调整开发环境 SourceMap 格式
+
+为了提供良好的调试体验，Modern.js 在开发环境下默认使用 webpack 提供的 `cheap-module-source-map` 格式 SourceMap。
+
+由于生成高质量的 SourceMap 需要额外的性能开销，通过调整开发环境的 SourceMap 格式，可以提升 dev 编译速度。
+
+比如禁用 SourceMap：
+
+```js title="modern.config.js"
+export default defineConfig({
+  tools: {
+    webpackChain(chain, { env }) {
+      if (env === 'development') {
+        chain.devtool(false);
+      }
+    },
+  },
+});
+```
+
+或是把开发环境的 SourceMap 格式设置为开销最小的 `eval` 格式：
+
+```js title="modern.config.js"
+export default defineConfig({
+  tools: {
+    webpackChain(chain, { env }) {
+      if (env === 'development') {
+        chain.devtool('eval');
+      }
+    },
+  },
+});
+```
+
+> 关于不同 SourceMap 格式之间的详细差异，请查看 [webpack - devtool](https://webpack.js.org/configuration/devtool/)。
+
+### 调整开发环境的 Browserslist 范围
+
+这项优化的原理与「提升 Browserslist 范围」类似，区别在于，我们可以为开发环境和生产环境设置不同的 browserslist，使开发环境下不需要引入额外的 Polyfill 编译逻辑。
+
+比如在 `package.json` 中添加以下配置，在开发环境下只兼容最新的浏览器，在生产环境下兼容实际需要的浏览器：
+
+```json
+{
+  "browserslist": {
+    "production": [">0.2%", "not dead", "not op_mini all"],
+    "development": [
+      "last 1 chrome version",
+      "last 1 firefox version",
+      "last 1 safari version"
+    ]
+  }
+}
+```
+
+注意，这项优化策略会导致 `dev` 构建的产物与 `build` 构建的产物存在一定差异。
+
+## build 优化策略
+
+以下是针对 `modern build` 进行提速的策略。
+
+### 禁用生产环境 SourceMap
+
+如果项目在生产环境下不需要 SourceMap，可以通过 `disableSourceMap` 配置项关闭，从而提升 build 构建的速度。
+
+```js title="modern.config.js"
+export default defineConfig({
+  output: {
+    disableSourceMap: true,
+  },
+});
+```
+
+详见 [output.disableSourceMap](/docs/configure/app/output/disable-source-map)。
+
+### 使用 esbuild 压缩
+
+Modern.js 基于 esbuild 提供了代码编译和压缩的能力，在大型工程中开启后，**可以大幅度减少代码压缩所需的时间，同时有效避免 OOM (heap out of memory) 问题**。
+
+使用 esbuild 压缩虽然带来了构建效率上的提升，但 esbuild 的压缩比例是低于 terser 的，因此**构建产物的体积会增大**，请根据业务情况酌情使用（比较适合中后台场景）。
+
+详见 [tools.esbuild](/docs/configure/app/tools/esbuild)。

package/zh/guides/topic-detail/framework-plugin/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "自定义插件",
+  "position": 6
+}

package/zh/guides/topic-detail/framework-plugin/abstract.md

@@ -0,0 +1,27 @@
+---
+sidebar_position: 1
+---
+
+# 插件可以做什么
+
+Modern.js 内置了一套插件系统，并基于这套插件系统来管理各个运行流程，Modern.js 的所有工程方案都是通过这套插件实现的，同时也支持开发者通过编写插件来扩展更多功能，适配复杂场景。
+
+由于 Modern.js 是基于这套插件系统实现的，因此可以说，Modern.js 中的所有能力是都对开发者开放的。包括但不限于：
+
+- 注册命令
+- 修改 Modern.js 配置、配置校验 Schema
+- 修改编译时的 Webpack/Babel/Less/Sass/Tailwind CSS/... 配置
+- 修改运行时需要渲染的 React 组件、Element
+- 修改页面路由
+- 修改服务器路由
+- 自定义控制台输出
+- 自定义动态 HTML 模版
+- 自定义 Node.js 服务器框架
+- 自定义 React 组件客户端/服务器端渲染
+- ...
+
+因此，当 Modern.js 暂时没有覆盖到你所需要的功能或场景时，可以开发一个自定义插件，来实现适配特殊场景的相关功能。
+
+:::info 补充信息
+关于 Modern.js 插件 API 的详细介绍，请参考 【[插件 API](/docs/apis/app/runtime/plugin/abstract)】。
+:::

package/zh/guides/topic-detail/framework-plugin/extend.md

@@ -0,0 +1,163 @@
+---
+sidebar_position: 4
+---
+
+# 扩展插件 Hook
+
+本章节介绍如何通过动态注册 [Hook 模型](/docs/apis/app/runtime/plugin/hook#hook-模型) 的方式来扩展插件 Hook。
+
+## 示例
+
+这里我们用一个简单的例子演示一下。假设我们要添加一些管理控制台输出信息的 Hook。
+
+首先我们初始化一个空的项目文件，并添加基础依赖：
+
+```console
+$ npx @modern-js/create modern-js-demo
+```
+
+### 创建 Hook
+
+我们先创建一个 Hook 模型：
+
+```ts title=config/plugin/MyPlugin.ts
+import { createWaterfall } from '@modern-js/plugin';
+
+const message = createWaterfall<string[]>();
+```
+
+然后注册它：
+
+```ts title=config/plugin/MyPlugin.ts
+import type { CliPlugin } from '@modern-js/core';
+
+export default (): CliPlugin => ({
+  name: 'my-plugin',
+
+  registerHook: {
+    message,
+  },
+});
+```
+
+添加 Hook 类型：
+
+```ts title=config/plugin/MyPlugin.ts
+declare module '@modern-js/core' {
+  export interface Hooks {
+    message: typeof message;
+  }
+}
+```
+
+### 使用 Hook
+
+创建插件，通过 `commands` Hook 函数，添加命令处理逻辑：
+
+```ts title=config/plugin/MyPlugin.ts
+import type { CliPlugin } from '@modern-js/core';
+
+export default (): CliPlugin => ({
+  name: 'my-plugin',
+
+  setup(api) {
+    return {
+      commands({ program }) {
+        program.command('message').action(async () => {
+          const hookRunners = api.useHookRunners();
+          const messages = hookRunners.message([]);
+          console.log(messages.join('\n'));
+        });
+      },
+    };
+  },
+});
+```
+
+最后 `config/plugin/MyPlugin.ts` 的状态是：
+
+```ts title=config/plugin/MyPlugin.ts
+import { createWaterfall } from '@modern-js/plugin';
+import type { CliPlugin } from '@modern-js/core';
+
+const message = createWaterfall<string[]>();
+
+export default (): CliPlugin => ({
+  name: 'my-plugin',
+
+  registerHook: {
+    message,
+  },
+
+  setup(api) {
+    return {
+      commands({ program }) {
+        program.command('message').action(async () => {
+          const hookRunners = api.useHookRunners();
+          const messages = hookRunners.message([]);
+          console.log(messages.join('\n'));
+        });
+      },
+    };
+  },
+});
+
+declare module '@modern-js/core' {
+  export interface Hooks {
+    message: typeof message;
+  }
+}
+```
+
+然后在 `modern.config.ts` 中添加这个插件：
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+import MyPlugin from './config/plugin/MyPlugin';
+
+export default defineConfig({
+  plugins: [MyPlugin()],
+});
+```
+
+这时运行 `npx modern message` 就会执行相关逻辑，但由于没有收集到任何信息，所以控制台输出为空。
+
+那这里我们添加一个：
+
+```ts title=config/plugin/OtherPlugin.ts
+import type { CliPlugin } from '@modern-js/core';
+
+export default (): CliPlugin => ({
+  name: 'my-plugin',
+
+  setup(api) {
+    return {
+      message(list) {
+        return [...list, '[foo] line 0', '[foo] line 1'];
+      },
+    };
+  },
+});
+```
+
+将它添加到配置中：
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+import MyPlugin from './config/plugin/MyPlugin';
+import OtherPlugin from './config/plugin/OtherPlugin';
+
+export default defineConfig({
+  plugins: [MyPlugin(), OtherPlugin()],
+});
+```
+
+这时运行 `npx modern message` 就可以在控制台看到信息了：
+
+```console
+$ modern message
+[foo] line 0
+[foo] line 1
+```
+
+以上面这种方式就可以扩展出拥有各种能力的插件 Hook。