@modern-js/main-doc 2.1.0 → 2.3.0

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

@@ -1,131 +0,0 @@
----
-title: 快速上手
-sidebar_position: 1
----
-
-## 环境准备
-
-import Prerequisites from '@site-docs/components/prerequisites.md'
-
-<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.md'
-
-<InitApp />
-
-## 启动项目
-
-import DebugApp from '@site-docs/components/debug-app.md'
-
-<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.md'
-
-<Deploy />

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

@@ -1,80 +0,0 @@
----
-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.md'
-
-<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.md

@@ -1,123 +0,0 @@
----
-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.md

@@ -1,147 +0,0 @@
----
-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 信息](/docs/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](/docs/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.md

@@ -1,56 +0,0 @@
----
-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 配置文件](/docs/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.md

@@ -1,49 +0,0 @@
----
-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` 文件用于记录当时进入预发布模式的一些状态信息，当出现状态信息和当前仓库状态不一致时，可直接删除该文件退出预发布模式。