@modern-js/main-doc 2.0.3-alpha.0 → 2.2.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/changelog.mdx

@@ -0,0 +1,238 @@
+---
+sidebar_position: 6
+---
+
+# 自定义 Changelog 生成
+
+Changesets 默认会使用 `@changesets/cli/changelog` 生成 Changelog 信息，如果默认的 Changelog 信息不能满足需求，可以自定义 Changelog 的生成。
+
+## 自定义 Changlog 内容
+
+Changelog 信息主要包含以下两种信息：
+
+- changeset 中写入的 Changelog 信息。
+
+- 本次版本升级关联包的版本变更信息。
+
+自定义逻辑主要实现两个函数，`getReleaseLine` 和 `getDependencyReleaseLine`，分别用来定义上述这两种信息。
+
+### getReleaseLine
+
+#### Params
+
+- changeset
+
+```ts
+export type VersionType = 'major' | 'minor' | 'patch' | 'none';
+
+export type Release = { name: string; type: VersionType };
+
+export type Changeset = {
+  id: string; // changeset 的文件名称
+  commit?: string; // changeset 提交时的 commit id 信息
+  summary: string; // changeset 内容信息
+  releases: Array<Release>; // 当前计算出的 changeset 升级包名称及类型信息
+};
+```
+
+- type
+
+当前包对应的升级版本类型，类型为上述 `VersionType`。
+
+#### 返回值
+
+Changelog 内容。
+
+#### 默认实现
+
+`@changesets/cli/changelog` 默认处理逻辑为将 `summary` 信息按照换行符 `\n` 分割，第一样前面增加 `-` 作为列表开头，其他内容作为第一行内容的补充整理在列表下方。
+
+```ts
+async function getReleaseLine(changeset, type) {
+  const [firstLine, ...futureLines] = changeset.summary
+    .split('\n')
+    .map(l => l.trimRight());
+
+  let returnVal = `- ${
+    changeset.commit ? `${changeset.commit}: ` : ''
+  }${firstLine}`;
+
+  if (futureLines.length > 0) {
+    returnVal += `\n${futureLines.map(l => `  ${l}`).join('\n')}`;
+  }
+
+  return returnVal;
+}
+```
+
+### getDependencyReleaseLine
+
+#### Params
+
+- changesets
+
+当前关联的所有 changeset 信息，类型为 `getReleaseLine` changeset 类型数组。
+
+- dependenciesUpdated
+
+```ts
+type ModCompWithPackage = {
+  name: string; // 依赖模块名称
+  type: VersionType; // 依赖模块的升级类型
+  oldVersion: string; // 依赖模块当前版本号
+  newVersion: string; // 依赖模块新版本号
+  changesets: string[]; // 关联的 changeset id 列表
+  packageJson: PackageJSON; // 依赖模块完整的 package.json 内容
+  dir: string; // 依赖模块的路径(绝对路径)
+};
+
+type DependenciesUpdated = ModCompWithPackage[];
+```
+
+#### 返回值
+
+Changelog 内容。
+
+#### 默认实现
+
+`@changesets/cli/changelog` 默认会使用 changesets 信息展示对应的 `Updated dependencies + commit id`，以列表形式展示。然后根据 `dependenciesUpdated` 信息展示对应的依赖包包名和新版本号，作为列表的子列表项。
+
+```ts
+async function getDependencyReleaseLine(changesets, dependenciesUpdated) {
+  console.log('getDependencyReleaseLine', changesets, dependenciesUpdated);
+  if (dependenciesUpdated.length === 0) return '';
+
+  const changesetLinks = changesets.map(
+    changeset =>
+      `- Updated dependencies${
+        changeset.commit ? ` [${changeset.commit}]` : ''
+      }`,
+  );
+
+  const updatedDepenenciesList = dependenciesUpdated.map(
+    dependency => `  - ${dependency.name}@${dependency.newVersion}`,
+  );
+
+  return [...changesetLinks, ...updatedDepenenciesList].join('\n');
+}
+```
+
+展示效果为：
+
+```markdown
+- Updated dependencies [f0438ab]
+- Updated dependencies [f0438ab]
+  - module-3@2.0.0
+  - module-1@0.2.0
+```
+
+## 配置
+
+Changesets 配置文件中 `changelog` 字段，该字段用于标记 Changelog 信息的获取途径。
+
+该配置可以为字符串，直接声明获取 Changelog 信息模块的模块名称或者路径。
+
+该配置还支持配置数组，数组中第一个元素为获取 Changelog 信息模块的模块名称或者路径，第二个元素为传入对应函数的参数值，会作为 `getReleaseLine` 和 `getDependencyReleaseLine` 函数的第三个参数传入。
+
+### 配置相对路径
+
+changelog 配置如果为相对路径为 `.changesets` 目录下的相对路径。
+
+例如创建 `.changeset/my-changelog-config.js` 文件，定义如下内容：
+
+```ts title=".changeset/my-changelog-config.js"
+async function getReleaseLine(changeset, type) {}
+
+async function getDependencyReleaseLine(changesets, dependenciesUpdated) {}
+
+module.exports = {
+  getReleaseLine,
+  getDependencyReleaseLine,
+};
+```
+
+`changlog` 配置为 `./my-changelog-config.js` 即可:
+
+```json title=".changesets/config.json"
+{
+  "changelog": "./my-changelog-config.js",
+   ...
+}
+```
+
+### 使用模块工程方案
+
+自定义 Changelog 还可以使用模块工程方案进行管理，提供通用方案。
+
+#### 使用 `npx @modern-js/create` 创建模块工程方案。
+
+```md
+? 请选择你想创建的工程类型 模块
+? 请填写项目名称 custom-changelog
+? 请选择开发语言 TS
+? 请选择包管理工具 pnpm
+```
+
+#### 实现自定义内容。
+
+```ts title="src/index.ts"
+export async function getReleaseLine() {}
+
+export async function getDependencyReleaseLine() {}
+```
+
+#### 将模块发布到 NPM。
+
+#### 在目标仓库根目录安装对应模块，例如 `custom-changelog`。
+
+#### 配置 changeset 的 changelog 配置为包名称。
+
+```json title=".changesets/config.json"
+{
+  "changelog": "custom-changelog",
+   ...
+}
+```
+
+### 使用 Monorepo 工程方案
+
+如果你当前仓库为 Monorepo 工程方案，可以直接使用模块子项目进行管理。
+
+#### 执行 `pnpm run new` 创建模块子项目。
+
+```md
+? 请选择你想创建的工程类型 模块
+? 请填写子项目名称 custom-changelog
+? 请填写子项目目录名称 custom-changelog
+? 请选择开发语言 TS
+```
+
+#### 实现自定义内容。
+
+```ts title="src/index.ts"
+export async function getReleaseLine() {}
+
+export async function getDependencyReleaseLine() {}
+```
+
+#### 在 Monorepo 根目录添加子项目模块依赖，例如 `custom-changelog`。
+
+```json title="package.json"
+{
+  "devDependencies": {
+    "custom-changelog": "workspace: *",
+    ...
+  }
+}
+```
+
+#### 配置 changeset 的 changelog 配置为包名称。
+
+```json title=".changesets/config.json"
+{
+  "changelog": "custom-changelog",
+   ...
+}
+```
+
+该模块发布到 NPM 后，依然可以和模块类型一样供其他仓库使用。