@modern-js/main-doc 2.52.0 → 2.53.0

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

@@ -1,231 +0,0 @@
----
-sidebar_position: 3
----
-
-# 发布正式版本
-
-发版正式版本时，我们需要根据开发过程中生成的 changesets 进行相关包版本号升级，并执行 publish 命令发布到 NPM 上。
-
-## 步骤
-
-:::info
-以下示例命令都以 pnpm 作为包管理工具进行，如果需要使用其他包管理工具，请按需求进行替换。
-
-:::
-
-### Modern.js Module
-
-#### 在根目录执行 bump 命令
-
-```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 工程方案
-
-#### 在根目录执行 bump 命令
-
-```bash
-pnpm run bump
-```
-
-![执行 bump 命令](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-monorepo-bump.png)
-
-执行该命令时，changesets 会自动进行以下操作：
-
-- 删除 `.changesets` 目录下的所有 changeset 文件。
-
-- 根据 changeset 信息升级相关包的版本号，除了显示写入 changeset 的包，执行命令时还会将 Monorepo 中所有的包进行依赖关系分析，如果需要升级，也会对应的自动升级版本号。
-
-- 在需要升级的包目录的 `CHANGELOG.md` 文件中写入 Changelog 信息，文件不存在时会自动创建。
-
-#### 确认并提交当前变更
-
-:::info
-需确认自动升级的版本号是否符合预期，如果需要了解版本升级策略，请查看[升级版本策略](/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，使用 `release` 命令在发布时将会自动去除 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` 发布包。
-
-```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/docs/zh/guides/topic-detail/model/test-model.mdx

@@ -1,45 +0,0 @@
----
-sidebar_position: 9
-title: 测试 Model
----
-# 测试 Model
-
-好的测试对代码的稳健性至关重要。下面以 [快速上手](/guides/topic-detail/model/quick-start) 的 `countModel` 为例，演示在 Modern.js 中，如何对 Model 进行单元测试。
-
-使用测试功能，需要先开启该功能。在项目根目录下，执行 `pnpm run new`，进行如下选择：
-
-```bash
-? 请选择你想要的操作 启用可选功能
-? 请选择功能名称 启用「单元测试 / 集成测试」功能
-```
-
-即可开启测试功能支持。
-
-新增 `count.test.ts` 文件，代码如下：
-
-```ts
-import { createStore } from '@modern-js/runtime/testing';
-import countModel from './count';
-
-describe('test model', () => {
-  it('count value should plus one after add', () => {
-    const store = createStore();
-    const [state, { add }] = store.use(countModel);
-
-    expect(state).toEqual({ value: 1 });
-
-    add();
-
-    expect(store.use(countModel)[0]).toEqual({ value: 2 });
-  });
-});
-```
-
-:::info
-这里使用的 [`createStore`](/apis/app/runtime/model/create-store) 是从 `@modern-js/runtime/testing` 导入的，内部会使用 [`runtime.state`](/configure/app/runtime/state) 的配置去创建 `store`。
-
-:::
-
-在测试用例里，我们新建一个 `store` 来挂载 `countModel`，通过 `store.use` 获取 `countModel` 的 State 和 Actions。然后调用 `add` Action 更新状态，并断言更新后的状态值。
-
-执行 `pnpm run test` 命令，触发测试用例的执行。

package/docs/zh/guides/topic-detail/monorepo/_category_.json

@@ -1,4 +0,0 @@
-{
-  "label": "Monorepo",
-  "position": 4
-}

package/docs/zh/guides/topic-detail/monorepo/create-sub-project.mdx

@@ -1,53 +0,0 @@
----
-sidebar_position: 2
----
-
-# 创建子项目
-
-本章将要介绍如何在 Monorepo 工程下创建子项目。
-
-> Modern.js 支持使用 pnpm 和 Yarn 的 Monorepo，这里以使用 pnpm 为例。以下命令可以以同样方式使用 Yarn 来执行。
-
-Modern.js 针对 Monorepo 工程提供了生成器功能，它用于在 Monorepo 工程下创建不同类型的 Monorepo 子项目。在生成器中提供以下类型子项目的创建：
-
-- 「应用」类型
-- 「模块」类型
-
-要启动 Monorepo 的生成器功能，可以在 Monorepo 工程根目录下执行命令：
-
-```
-pnpm run new
-```
-
-:::info 补充信息
-使用 Yarn 的方式：`yarn new`
-
-:::
-
-执行成功后，可以看到如下内容：
-
-```
-? 请选择你想创建的工程类型 (Use arrow keys)
-❯ Web 应用
-  Npm 模块
-```
-
-然后根据不同的需求选择对应的类型项目选项，选择之后便开始出现对应子项目类型的问题和选项。例如选择「应用」后会出现：
-
-```
-? 请选择你想创建的工程类型：Web应用
-? 请填写子项目名称
-```
-
-当完成所有生成器问题之后，便开始进行项目的创建和项目依赖的下载。当创建成功之后，可以看到类似以下内容：
-
-```
-[INFO] 依赖自动安装成功
-[INFO] 创建成功！
-可在新项目的目录下运行以下命令：
-pnpm run dev          # 启动开发服务器
-pnpm run build        # 构建生产环境产物
-pnpm run serve        # 启动生产环境服务
-pnpm run lint         # 运行 ESLint 并自动修复问题
-pnpm run new          # 启用可选功能或创建项目要素
-```

package/docs/zh/guides/topic-detail/monorepo/intro.mdx

@@ -1,14 +0,0 @@
----
-sidebar_position: 1
----
-
-# Monorepo 工程介绍
-
-Modern.js 提供了对于 Monorepo 工程方案的支持，其主要通过 `@modern-js/monorepo-tools` 来提供功能。
-
-该专题将从以下方面来讲解如何使用 Modern.js 对 Monorepo 进行管理：
-
-- 在 Monorepo 中创建子项目
-- Monorepo 下子项目之间的联调开发
-- 发布 Monorepo 的子项目
-- 部署 Monorepo 子项目

package/docs/zh/guides/topic-detail/monorepo/publish.mdx

@@ -1,69 +0,0 @@
----
-sidebar_position: 4
----
-
-# 可复用模块的发布
-
-在 Monorepo 中有时会需要把多个模块项目发布到 [NPM](https://www.npmjs.com/) 上，本章将要介绍如果在 Monorepo 中对子项目进行版本更新以及发布。
-
-## 准备工作
-
-接着 [子项目联调](/guides/topic-detail/monorepo/sub-project-interface) 章节的例子，我们对 `components` 模块进行发布。
-
-## 生成变更记录
-
-在开发阶段，当某个模块的功能开完完成之后，一般需要提交代码（例如提交到 [GitHub](https://github.com/) 上）并需要记录本次修改的内容。在 Modern.js 的 Monorepo 工程中，我们可以在 monorepo 根目录执行命令：
-
-```
-pnpm run change
-```
-
-然后根据提示选择变更或者将要发布的包以及选择包升级的版本，并填写变更信息。变更信息的内容可以包含此次开发的功能、修复的问题等。
-
-那么对于上面的例子，我们选择变更的项目为 `components`，并填写此次变更的内容：
-
-```
-$ modern change
-🦋  Which packages would you like to include? · components
-🦋  Which packages should have a major bump? · No items were selected
-🦋  Which packages should have a minor bump? · components
-🦋  Please enter a summary for this change (this will be in the changelogs). Submit empty line to open external editor
-🦋  Summary · add features
-🦋  === Releasing the following packages ===
-🦋  [Minor]
-🦋    components
-🦋  ╔════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
-🦋  ║                                                      ========= NOTE ========                                                       ║
-🦋  ║All dependents of these packages that will be incompatible with the new version will be patch bumped when this changeset is applied.║
-🦋  ╚════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
-🦋  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 /Users/demo/modern-js/official/monorepo-pnpm/.changeset/silent-tigers-run.md
-```
-
-该命令完成后，在 `.changeset` 中会有新的 `silent-tigers-run.md` 文件生成，其中包含了刚刚填写的信息，这些新生成的文件将用于后面发布流程中使用。**因此在提交代码的时候，需要将`.changeset` 目录下的文件一并提交**。
-
-## 版本更新
-
-在模块发布之前，还需要将模块的版本进行更新。。在 Modern.js 的 Monorepo 工程中，可以在 Monorepo 项目根目录下执行：
-
-```
-pnpm run bump
-```
-
-该命令会根据之前生成在 `.changeset` 目录下的文件自动更新对应模块的版本号和 CHANGELOG 信息，执行成功后会看到：
-
-```
-🦋  All files have been updated. Review them and commit at your leisure
-```
-
-## 发布
-
-最后执行 `pnpm run prepare --filter {./packages} && pnpm run release`，便可以发布对应的模块了。
-
-:::info 补充信息
-在上面的命令中 --filter \{./packages\} 用于筛选位于 `./packages` 目录下的子项目，可以通过 [PNPM Filtering](https://pnpm.io/filtering) 来了解更多它的使用。
-
-:::

package/docs/zh/guides/topic-detail/monorepo/sub-project-interface.mdx

@@ -1,143 +0,0 @@
----
-sidebar_position: 3
----
-
-# 子项目联调
-
-本章将要介绍如何在 Monorepo 下进行子项目之间的联调使用。
-
-## 准备工作
-
-按照 [「创建子项目」](/guides/topic-detail/monorepo/create-sub-project) 章节的介绍（如果还没有看过，可以先了解一下），我们首先创建以下三个子项目：
-
-- 一个「应用」子项目
-- 一个「模块」子项目
-
-执行 `pnpm run new`，并按照如下进行选择：
-
-**「应用」子项目：**
-
-```
-? 请选择你想创建的工程类型：Web 应用
-? 请填写子项目名称：app
-? 请填写子项目目录名称：app
-? 请选择开发语言：TS
-```
-
-**「模块」子项目：**
-
-```
-? 请选择你想创建的工程类型：Npm 模块
-? 请填写子项目名称：components
-? 请填写子项目目录名称：components
-? 请选择开发语言：TS
-```
-
-创建成功后，会得到以下项目：
-
-- `./apps/app`
-- `./packages/components`
-
-然后修改一下默认的代码和新增文件：
-
-**重命名 `./packages/components/src/index.tsx`**
-
-```tsx
-import './index.css';
-
-export default function ({ text }: { text: string }) {
-  return (
-    <div>
-      This is UI Components Log: <p className="log">{text}</p>
-    </div>
-  );
-}
-```
-
-**新增 `./packages/components/src/index.css`**
-
-```css
-.log {
-  color: gray;
-}
-```
-
-**修改 `./apps/app/src/App.tsx`**
-
-```tsx
-import { Switch, Route } from '@modern-js/runtime/router';
-import Comp from 'components';
-
-import './App.css';
-
-const App = () => (
-  <Switch>
-    <Route exact={true} path="/">
-      <div className="container-box">
-        <Comp text="hello world" />
-        {/* 省略... */}
-      </div>
-    </Route>
-    <Route path="*">
-      <div>404</div>
-    </Route>
-  </Switch>
-);
-
-export default App;
-```
-
-到此为止我们创建了一个可以被发布到外部的组件项目以及一个使用组件的应用项目，如果直接运行应用项目还暂时无法正常使用。接下来将要介绍如何让它们能够互相联调使用，成功的使应用子项目 `apps/app` 正常运行。
-
-:::info
-启动 `apps/app` 项目之前需要先构建（`pnpm run build`） `packages/component`。
-
-:::
-
-由于 Modern.js 支持 pnpm 与 Yarn 的 Monorepo 工程，接下来会从这两个方面分别介绍。
-
-## 在使用 pnpm 的 Monorepo 中进行项目联调
-
-在 pnpm 的 Monorepo 项目中，我们通过在 `apps/app` 子项目下执行以下命令，将 `packages/components` 子项目加入到应用的依赖列表当中。
-
-```
-pnpm add components
-```
-
-执行成功后，在 `apps/app/package.json` 会发生如下变化：
-
-```json
-{
-  "dependencies": {
-++  "components": "workspace:^0.1.0"
-  },
-}
-```
-
-:::info 补充信息
-`workspace:^0.1.0` 是一种 PNPM 提供的 [Workspace 协议](https://pnpm.io/workspaces#workspace-protocol-workspace)。
-
-:::
-
-当依赖安装成功之后，我们还需要将 `packages/components` 进行构建，因为需要使用其构建产物。
-
-到此为止，`app/apps` 应用子项目可以正常的运行了。在修改 `packages/components` 的源码并构建之后，会触发应用子项目的热更新。
-
-## 在使用 Yarn 的 Monorepo 中进行项目联调
-
-在 Yarn 的 Monorepo 项目中，默认情况下可以直接在 `apps/app` 应用项目中直接使用组件项目。
-
-:::info 补充信息
-之所以可以直接在应用中使用组件项目，是因为 Yarn 将这些子项目模块提升到了顶层的 `node_modules`内。
-
-:::
-
-但是考虑到依赖关系的严谨性，建议在 `apps/app/package.json` 中进行显式依赖声明：
-
-```json
-{
-  "dependencies": {
-++  "components": "0.1.0"
-  },
-}
-```