@modern-js/main-doc 2.1.0 → 2.3.0

package/zh/guides/get-started/quick-start.mdx

@@ -0,0 +1,132 @@
+---
+title: 快速上手
+sidebar_position: 1
+---
+# 快速上手
+
+## 环境准备
+
+import Prerequisites from "@site-docs/components/prerequisites"
+
+<Prerequisites />
+
+## 安装
+
+Modern.js 提供了 `@modern-js/create` 生成器来创建项目，不要全局安装，使用 `npx` 按需运行。
+
+可以使用已有的空目录来创建项目：
+
+```bash
+mkdir myapp && cd myapp
+npx @modern-js/create
+```
+
+也可以直接用新目录创建项目：
+
+```bash
+npx @modern-js/create myapp
+```
+
+## 初始化项目
+
+import InitApp from "@site-docs/components/init-app"
+
+<InitApp />
+
+## 启动项目
+
+import DebugApp from "@site-docs/components/debug-app"
+
+<DebugApp />
+
+## 使用配置
+
+通过生成器创建的 Modern.js 项目中，存在 `modern.config.ts` 文件。
+
+可以通过配置文件来开启功能，或覆盖 Modern.js 的默认行为。例如添加如下配置，开启 SSR：
+
+```ts
+import appTools, { defineConfig } from '@modern-js/app-tools';
+
+// https://modernjs.dev/docs/apis/app/config
+export default defineConfig({
+  runtime: {
+    router: true,
+    state: true,
+  },
+  server: {
+    ssr: true,
+  },
+  plugins: [appTools()],
+});
+```
+
+重新执行 `pnpm run dev`，在浏览器 Network 菜单中，可以发现项目已经在服务端完成了页面渲染。
+
+## 构建项目
+
+在项目中执行 `pnpm run build` 即可构建项目生产环境产物：
+
+```bash
+$ pnpm run build
+
+> modern build
+
+info    Create a production build...
+
+info    File sizes after production build:
+
+  File                                      Size         Gzipped
+  dist/static/js/lib-corejs.ffeb7fb8.js     214.96 kB    67.23 kB
+  dist/static/js/lib-react.09721b5c.js      152.61 kB    49.02 kB
+  dist/static/js/218.102e2f39.js            85.45 kB     28.5 kB
+  dist/static/js/lib-babel.a7bba875.js      11.93 kB     3.95 kB
+  dist/html/main/index.html                 5.84 kB      2.57 kB
+  dist/static/js/main.3568a38e.js           3.57 kB      1.44 kB
+  dist/static/css/async/304.c3c481a5.css    2.62 kB      874 B
+  dist/asset-manifest.json                  1.48 kB      349 B
+  dist/static/js/async/304.c45706bc.js      1.4 kB       575 B
+  dist/static/js/async/509.fcb06e14.js      283 B        230 B
+
+ Client ✔ done in 3.57s
+```
+
+构建产物默认生成到 `dist/`，目录结构如下：
+
+```
+.
+├── asset-manifest.json
+├── html
+│   └── main
+├── loader-routes
+│   └── main
+├── modern.config.json
+├── route.json
+└── static
+    ├── css
+    └── js
+```
+
+## 本地验证
+
+在项目中执行 `pnpm run serve` 即可在本地验证构建产物是否正常运行：
+
+```bash
+$ pnpm run serve
+
+> modern serve
+
+Starting the modern server...
+info    App running at:
+
+  > Local:    http://localhost:8080/
+  > Network:  http://192.168.0.1:8080/
+```
+
+在浏览器中打开 `http://localhost:8000/`，内容应该和 `pnpm run dev` 时一致。
+
+## 部署
+
+import Deploy from "@site-docs/components/deploy"
+
+<Deploy />

package/zh/guides/get-started/upgrade.mdx

@@ -0,0 +1,83 @@
+---
+title: 升级
+sidebar_position: 2
+---
+# 升级
+
+## 通过命令行升级
+
+Modern.js 提供了 `upgrade` 命令支持项目升级到最新的 Modern.js 版本。
+
+在项目中执行 `pnpm run upgrade`：
+
+```bash
+$ pnpm run upgrade
+
+> modern upgrade
+
+[INFO] [项目类型]: 应用
+[INFO] [Modern.js 最新版本]: 2.0.0
+[INFO] 已更新 Modern.js 依赖至最新版本!
+```
+
+可以看到项目 `package.json` 中的依赖已经更改到最新。
+
+## 指定版本升级
+
+Modern.js 所有的官方包目前都使用**统一版本号**进行发布。
+
+import ReleaseNote from "@site-docs/components/release-note"
+
+<ReleaseNote />
+
+:::tip
+当升级时，需要对 Modern.js 官方提供的所有包做统一升级，而不是升级单个依赖。
+
+:::
+
+## 锁定子依赖
+
+当项目某个子依赖出现问题，而 Modern.js 无法立即更新时，可以使用包管理器锁定子依赖版本。
+
+### pnpm
+
+对于使用 pnpm 的项目，请在**项目根目录**的 `package.json` 中添加以下配置，然后重新执行 `pnpm install`：
+
+```json
+{
+  "pnpm": {
+    "overrides": {
+      "package-name": "^1.0.0"
+    }
+  }
+}
+```
+
+### Yarn
+
+对于使用 Yarn 的项目，请在**项目根目录**的 `package.json` 中添加以下配置，然后重新执行 `yarn install`：
+
+```json
+{
+  "resolutions": {
+    "package-name": "^1.0.0"
+  }
+}
+```
+
+### Npm
+
+对于使用 Npm 的项目，请在**项目根目录**的 `package.json` 中添加以下配置，然后重新执行 `npm install`：
+
+```json
+{
+  "overrides": {
+    "package-name": "^1.0.0"
+  }
+}
+```
+
+:::info
+对于 Monorepo 仓库，只能在项目根目录的 `package.json` 中锁定依赖版本，并且会影响 Monorepo 中的所有 package。
+
+:::

package/zh/guides/topic-detail/changesets/add.mdx

@@ -0,0 +1,124 @@
+---
+sidebar_position: 2
+---
+
+# 添加一个 changeset
+
+当我们开发完成一个功能时，需要添加一个 changeset 用于声明当前功能，用于后续版本发布。
+
+## 信息
+
+一个 changeset 包含的内容包括：
+
+- 本次变更涉及哪些包的变更。
+
+- 本次变更需要升级的版本号类型，类型符合 [semver](https://semver.org/) 规范。
+
+- 本次变更的 Changelog 信息。
+
+## 步骤
+
+:::info
+以下示例命令都以 pnpm 作为包管理工具进行，如果需要使用其他包管理工具，请按需求进行替换。
+
+:::
+
+### 模块工程方案
+
+#### 在根目录执行以下命令：
+
+```bash
+pnpm run change
+```
+
+#### 选择本次变更需要升级的版本号类型，点击回车：
+
+![选择版本类型](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-select-version.png)
+
+#### 填入 Changelog 信息，并点击两次回车：
+
+![写入变更信息](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-input-changelog.png)
+
+执行完成后，将在项目的 `.changeset` 目录创建对应的 changeset 文件，文件内容如下：
+
+```markdown
+---
+'module-changeset': patch
+---
+
+feat: test module solution changeset
+```
+
+该文件中包含了 changeset 的所有信息。
+
+### Monorepo 工程方案
+
+我们假设 monorepo 中存在三个模块包，分别为 `module-1`，`module-2`，`module-3`。
+
+#### 在根目录执行以下命令：
+
+```bash
+pnpm run change
+```
+
+#### 选择本次需要升级的包列表：
+
+Changesets 会根据当前代码变更(`git diff Head...baseBranch`)，将 Monorepo 中的 package 分为两类，`changed packages` 和 `unchanged packages`，方便用户进行选择。
+
+使用空格键选择对应的包或者分类即可，选择完成后点击回车：
+
+![选择升级包](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-select-packages.png)
+
+#### 分别选择不同版本类型对应的包，changeset 会询问 `major` 和 `minor` 类型，如果存在包未选择这两种类型，将会默认使用 `patch` 类型：
+
+![选择升级包版本类型](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-auto-select-patch.png)
+
+#### 填入 Changelog 信息，并点击两次回车：
+
+![写入变更信息](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-input-changelog-monorepo.png)
+
+执行完成后，将在项目的 `.changeset` 目录创建对应的 changeset 文件，文件内容如下：
+
+```markdown
+---
+'module-2': minor
+'module-3': patch
+---
+
+feat: test-changeset
+```
+
+该文件中包含了 changeset 的所有信息，不同的包也会根据选择的版本类型进行标记。
+
+## 参数
+
+change 命令支持以下参数：
+
+- `--empty` 添加一个空的 changeset。
+
+```bash
+pnpm run change -- --empty
+```
+
+执行完成后，将在项目的 `.changeset` 目录创建空的 changeset 文件，文件内容如下：
+
+```markdown
+---
+---
+```
+
+- `--open` 使用该参数时，在填写 Changelog 步骤会打开系统默认编辑器进行填写。
+
+## 注意事项
+
+- 不是所有的变更都需要 changeset
+
+如果当前变更是修改仓库的一些基础设施，比如 CI、测试等，就不需要添加 changeset 或者可以添加一个空的 changeset。
+
+- 一个 pull reuqest 可以提交多个 changeset
+
+当一个 pull request 存在多个功能开发或者问题修复时，可以多次执行 `pnpm run change` 添加多个 changeset 文件，每个文件选择对应功能的包和添加变更信息即可。
+
+- 创建 changeset 时，需要选择该功能相关的所有包
+
+在 Monorepo 中创建 changeset 时，需要选中和该功能相关的所有变更包，避免出现发版时部分包未发布的情况。

package/zh/guides/topic-detail/changesets/config.mdx

@@ -0,0 +1,147 @@
+---
+sidebar_position: 5
+---
+
+# Changesets 配置文件
+
+我们前面了解到，初始化 Modern.js 仓库时，会默认初始化 Changesets 的配置文件，即 `.changeset/config.json` 文件，下面我们将详细了解一下该文件中支持哪些配置。
+
+## 配置介绍
+
+### commit
+
+类型： `boolean`
+
+默认值： `false`
+
+当配置该字段为 `true` 时，在执行 `change` 和 `bump` 命令时，将自动执行提交代码操作。
+
+默认的 commit 信息格式如下：
+
+![change commit](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-change-commit-info.png)
+![bump commit](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-bump-commit-info.png)
+
+该 commit 信息支持自定义，我们将在[自定义提交 commit 信息](/guides/topic-detail/changesets/commit)章节进行详细介绍。
+
+### access
+
+类型：`restricted` | `public`
+
+默认值：`restricted`
+
+用于配置当前包的发布形式，如果配置为 `restricted`，将作为私有包发布，如果为 `public`，则发布公共范围包。
+
+对于仓库中存在部分包需要配置 access，可以在 `package.json` 中配置 `publishConfig`，例如：
+
+```json title=package.json
+{
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}
+```
+
+对于不需要发布的包，可以在 `package.json` 中设置 `private` 为 `true`，阻止其进行发布。
+
+### baseBranch
+
+类型： `string`
+
+默认值： `main`
+
+仓库主分支。该配置用于计算当前分支的变更包并进行分类。
+
+### ignore
+
+类型：`string[]`
+
+默认值：`[]`
+
+用于声明执行 `bump` 命令时忽略的包，和 `bump` 命令的 `--ignore` 参数用法一致，注意两者不能同时使用。
+
+### fixed
+
+类型： `string[][]`
+
+默认值：`[]`
+
+用于 monorepo 中对包进行分组，相同分组中的包版本号将进行绑定，每次执行 `bump` 命令时，同一分组中的包只要有一个升级版本号，其他会一起升级。
+支持使用正则匹配包名称。
+
+### linked
+
+类型： `string[][]`
+
+默认值：`[]`
+
+和 `fixed` 类似，也是对 monorepo 中对包进行分组，但是每次执行 `bump` 命令时，只有和 changeset 声明的变更相关的包才会升级版本号，同一分组的变更包的版本号将保持一致。
+支持使用正则匹配包名称。
+
+### updateInternalDependencies
+
+类型：`patch` | `minor`
+
+默认值：`patch`
+
+用于声明更新内部依赖的版本号规则。
+
+当执行 `bump` 命令升级版本号时，默认会自动更新仓库中使用该包的依赖声明。配置该字段为 `minor` 后，如果升级版本号为 `patch` 类型，将不会自动更新引用依赖声明。
+
+例如：
+
+```
+pkg-a @ version 1.0.0
+pkg-b @ version 1.0.0
+  depends on pkg-a at range `^1.0.0
+```
+
+默认情况下，升级 `pkg-a` 至 `1.0.1` 时，会更新 `pkg-b` 中的 `pkg-a` 的依赖版本为 `^1.0.1`。
+
+当配置 `updateInternalDependencies` 为 `minor` 时，升级 `pkg-a` 至 `1.0.1` 时，`pkg-b` 中的 `pkg-a` 的依赖版本将不会更新，只有 `pkg-a` 升级版本号为 `1.1.0` 或者 `2.0.0` 时，才会更新 `pkg-b` 中的 `pkg-a` 的依赖。
+
+### changelog
+
+类型：`boolean` | `string` | `[string, unknow]`
+
+默认值：`@changesets/cli/changelog`
+
+生成 Changelog 规则。
+
+配置为 `false` 时，执行 bump 命令时，在 `CHANGELOG.md` 文件中只声明版本号，不声明其他 Changelog 信息。
+
+![关闭 changelog 配置](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-empty-changelog.png)
+
+配置为 `@changesets/cli/changelog` 将使用官方提供的 Changlog 生成规则，将 changeset 信息转换为 Changlog 内容。
+
+配置为数组时，第一个参数为自定义 NPM 包或者路径，第二个参数为需要传入的默认参数配置，自定义格式我们将在后续[自定义 Changelog](/guides/topic-detail/changesets/changelog) 章节讲解。
+
+### \_\_\_experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH
+
+一些实验性配置。
+
+#### onlyUpdatePeerDependentsWhenOutOfRange
+
+类型：`boolean`
+
+默认值：`false`
+
+针对于 `peerDependence` 依赖的升级策略配置，默认针对 `peerDependence` 在 `minor` 和 `major` 版本升级时，当前包会升级大版本。
+
+该配置设置为 true 时，仅当 `peerDependence` 声明包依赖超出声明范围时才更新版本。
+
+#### updateInternalDependents
+
+类型： `always` | `out-of-range`
+
+默认值：`always`
+
+当执行 `bump` 命令升级版本号时，默认会自动更新仓库中使用该包的依赖声明。当设置该参数为 `out-of-range` 时，只有当依赖声明超出范围时才会更新仓库中使用该包的依赖声明。
+
+#### useCalculatedVersionForSnapshots
+
+类型：`boolean`
+
+默认值：`false`
+
+使用快照发布时，默认会使用 `0.0.0-timestamp` 的版本格式，保证用户可以正常使用预发布版本。当你需要忽略上述问题，使用正常的版本号格式时，即当前版本为 `1.0.1` 快照版本期望使用`1.0.1-timestamp`，可配置该参数为 `true`。

package/zh/guides/topic-detail/changesets/introduce.mdx

@@ -0,0 +1,56 @@
+---
+sidebar_position: 1
+---
+
+# 认识 Changesets
+
+Modern.js 默认集成了 [Changesets](https://github.com/changesets/changesets) 用于模块和 Monorepo 工程方案项目中的包版本管理。
+
+## 特点
+
+Changesets 具有以下几个特点：
+
+- 在开发时，需要开发者提供本次变更涉及的包名称、升级版本类型(`pathch`、`minor`、`major`)及变更信息，即 changeset。
+
+- 在发布版本时，会根据 changeset 自动升级对应包的版本号，并在对应的包中生成 Changelog 信息。
+
+- 在 Monorepo 场景中，changeset 会自动生成仓库依赖图，升级时只会升级变更包及相关依赖包的版本号。
+
+## 初始化
+
+Modern.js 默认创建的模块和 Monorepo 工程方案项目已经初始化完成 Changesets，在项目根目录会自动创建 `.changeset` 目录，及 `.changeset/config.json` 的配置文件。
+
+并且，Modern.js 在其对应的工程方案工具 `@modern-js/module-tools` 和 `@modern-js/monorepo-tools` 提供了 Changesets 相应的命令，无需再手动安装 Changesets 相关依赖。
+
+Changesets 默认配置如下：
+
+```json title=".changeset/config.json"
+{
+  "$schema": "https://unpkg.com/@changesets/config@2.0.0/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "linked": [],
+  "access": "restricted",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}
+```
+
+配置文件提供了生成 Changesets 的一些基本配置，字段详细介绍请参考后续章节： [Changesets 配置文件](/guides/topic-detail/changesets/config)。
+
+## 命令
+
+- `change` 创建一个 changeset，执行完成该命令后会自动在 `.changeset` 目录生成一个 changeset 文件。
+
+- `bump` 根据当前 changeset 升级对应包版本号。
+
+- `pre` 标记进入和退出 `pre release` 模式，在 `pre release` 模式下执行 `bump` 命令，将会生成 `x.x.x-${pre-tag}.x` 的版本号格式。
+
+- `release` 发布包到 NPM。
+
+- `status` 查看当前 changeset 状态。
+
+- `gen-release-note` 根据当前的 chagneset 状态生成 Release Note 信息。
+
+具体命令支持的参数可以查看后续对应章节介绍。

package/zh/guides/topic-detail/changesets/release-pre.mdx

@@ -0,0 +1,50 @@
+---
+sidebar_position: 4
+---
+
+# 发布预发布版本
+
+在发布正式版本之前，我们也需要发布预发布版本供内部测试和用户使用，Changesets 也支持发布预发布版本。
+
+## 步骤
+
+:::info
+以下示例命令都以 pnpm 作为包管理工具进行，如果需要使用其他包管理工具，请按需求进行替换。
+
+:::
+
+#### 执行以下命令升级预发布版本版本号：
+
+```bash
+pnpm run bump -- --canary --preid <preid>
+```
+
+`preid` 为预发布版本标记，例如 `alpha`、`beta` 等，默认值为 `next`。
+
+使用 `--canary` 参数后，`bump` 命令由以下三个步骤完成：
+
+- `changeset pre enter <preid>` 进入预发布模式
+
+- `changeset version` 升级版本号
+
+- `changeset pre exit` 退出预发布模式
+
+#### 检查相关变更并提交
+
+检查相关版本号变更是否正确，并提交变更。
+
+建议预发布操作不在主分支上进行，不合入主分支，当预发布验证完成后，直接基于主分支发布正式版本。
+
+#### 执行以下命令发布预发布版本：
+
+```bash
+pnpm run release -- --tag <tag>
+```
+
+发布预发布版本一定要使用 `--tag` 参数，参数值最好和 `preid` 值相同，方便用户使用。
+
+## 注意事项
+
+### 退出预发布模式
+
+在进入预发布模式后，Changesets 会自动在 `.changeset` 目录创建 `pre.json` 文件用于记录当时进入预发布模式的一些状态信息，当出现状态信息和当前仓库状态不一致时，可直接删除该文件退出预发布模式。