@modern-js/main-doc 2.7.0 → 2.9.0

package/docs/zh/guides/basic-features/mock.mdx

@@ -0,0 +1,99 @@
+---
+title: 数据模拟
+sidebar_position: 6
+---
+# 数据模拟
+
+Modern.js 提供了快速生成 Mock 数据的功能，能够让前端独立自主开发，不被后端接口阻塞。
+
+## Mock 文件
+
+约定当 `config/mock` 目录下存在 `index.[jt]s` 时，会自动开启 Mock 功能，如下：
+
+```bash
+.
+├── config
+│   └── mock
+│       └── index.ts
+├── src
+│   └── App.tsx
+└── modern.config.ts
+```
+
+## 编写 Mock 文件
+
+`config/mock/index.ts` 文件只需要导出一个包含所有 Mock API 的对象，对象的属性由请求配置 `method` 和 `url` 组成，对应的属性值可以为 `Object`、`Array`、`Function`：
+
+```js
+export default {
+  /* 属性为具体的 method 和 请求 url，值为 object 或 array 作为请求的结果 */
+  'GET /api/getInfo': { data: [1, 2, 3, 4] },
+
+  /* method 默认为 GET */
+  '/api/getExample': { id: 1 },
+
+  /* 可以使用自定义函数根据请求动态返回数据，返回值参考 express middleware */
+  'POST /api/addInfo': (req, res, next) => {
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.end('200');
+  },
+};
+```
+
+代码中访问 `http://localhost:8080/api/getInfo` 时，接口会返回 JSON 格式数据：`{ "data": [1, 2, 3, 4] }`。
+
+## 返回随机数据
+
+可以在 `config/mock/index.js` 中自主引入 [Mock.js](https://github.com/nuysoft/Mock/wiki/Getting-Started) 等库生成随机数据，例如：
+
+```js
+const Mock = require('mockjs');
+
+module.exports = {
+  '/api/getInfo': Mock.mock({
+    'data|1-10': [{ name: '@cname' }],
+  }) /* => {data: [{name: "董霞"}, {name: "魏敏"},  {name: "石磊"}} */,
+};
+```
+
+:::info 更多随机数据生成库
+
+- [Chancejs](https://github.com/chancejs/chancejs)
+- [Mock](https://github.com/nuysoft/Mock/wiki/Getting-Started)
+
+:::
+
+## 延迟返回
+
+- 可以使用浏览器「 弱网模拟 」的功能实现。
+- 可以通过 `setTimeout` 为单个接口设置延迟，例如：
+
+```js
+module.exports = {
+  'api/getInfo': (req, res) => {
+    setTimeout(() => {
+      res.end('delay 2000ms');
+    }, 2000);
+  },
+};
+```
+
+## 按需使用 Mock 服务
+
+`config/mock/index.ts` 下还可以到处 `config` 对象，更精细的控制 Mock 服务。
+
+```ts
+type MockConfig = {
+  enable: ((req: IncomingMessage, res: ServerResponse) => boolean) | boolean;
+};
+
+export const config = {
+  enable: false
+}
+```
+
+目前仅支持 `enable` 配置，开发者可以通过该配置控制是否执行 Mock。
+
+:::note
+修改 `config` 后无需重启服务，即刻生效。
+:::

package/docs/zh/guides/concept/builder.mdx

@@ -0,0 +1,47 @@
+---
+sidebar_position: 2
+---
+
+# 构建引擎
+
+**Modern.js 的构建能力由 [Modern.js Builder](https://modernjs.dev/builder) 提供。**
+
+Modern.js Builder 是 Modern.js 体系的核心组件之一，它是一个面向 Web 开发场景的构建引擎，可以脱离 Modern.js 被独立使用。Modern.js Builder 同时支持 webpack 和 Rspack 等多种打包工具，默认情况下使用最成熟的 webpack 进行打包。
+
+## 构建架构
+
+从构建的角度看，Modern.js 分为三层架构，从上到下依次是：
+
+- 上层研发框架：Modern.js。
+- 通用构建引擎：Modern.js Builder。
+- 底层打包工具：webpack 和 rspack。
+
+<img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/builder-layers-1117.png" style={{ maxWidth: '540px' }} />
+
+## 构建文档
+
+由于 Modern.js Builder 是一个可独立使用的模块，我们为它提供了单独的文档，文档地址为：[modernjs.dev/builder](https://modernjs.dev/builder)。
+
+在该文档中，你可以了解到 Modern.js Builder 的详细介绍，同时也可以找到各个构建能力的完整使用指南。当你遇到构建方面的需求或问题时，建议你优先阅读 Modern.js Builder 文档来解决。
+
+## 构建配置
+
+Modern.js 的配置继承自 Modern.js Builder，因此你可以在 Modern.js 中使用 Modern.js Builder 提供的所有构建配置。
+
+以 Modern.js Builder 的 `html.title` 配置项为例，你可以直接在 `modern.config.ts` 文件中使用该配置项，它会被自动传递给 Modern.js Builder。
+
+```ts title="modern.config.js"
+export default defineConfig({
+  html: {
+    title: 'example',
+  },
+});
+```
+
+关于构建配置的详细说明，请参考 [「Modern.js Builder - Builder 配置」](https://modernjs.dev/builder/guide/basic/builder-config.html)。
+
+## 构建能力
+
+Modern.js Builder 提供了丰富的构建能力，包括 JavaScript 编译、CSS 编译、静态资源处理、代码热更新、代码压缩、TS 类型检查等几十种能力。
+
+我们推荐你阅读 [「Modern.js Builder - 功能导航」](https://modernjs.dev/builder/guide/features.html) 来了解 Modern.js Builder 提供的所有构建能力。

package/docs/zh/guides/get-started/introduction.mdx

@@ -0,0 +1,47 @@
+---
+title: 介绍
+sidebar_position: 1
+---
+
+# Modern.js 介绍
+
+**Modern.js 是字节跳动 Web 工程体系的开源版本**，它提供多个解决方案，来帮助开发者解决不同研发场景下的问题。
+
+目前 Modern.js 包含三个解决方案，分别面向 Web 应用开发场景、npm 包开发场景和文档站开发场景：
+
+![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/Solutions-1311.png)
+
+作为 Modern.js 工程体系的一部分，以上每个解决方案都可以被单独使用，并且各自部署了独立的文档站点。开发者可以按需选择其中的一个或多个解决方案来使用。
+
+## 关于文档
+
+**当前文档站对应的是 Modern.js 框架**，适用于开发 Web 应用。
+
+- 如果你需要开发一个 npm 包，请移步至 [Modern.js Module](https://modernjs.dev/module-tools) 文档。
+- 如果你需要开发一个文档站点，请移步至 [Modern.js Doc](https://modernjs.dev/doc-tools/zh) 文档。
+- 如果你需要基于 Modern.js 的构建引擎来实现一个 Web 开发框架，请移步至 [Modern.js Builder](https://modernjs.dev/builder) 文档。
+
+:::tip
+由于 Modern.js 框架的使用最为广泛，在本文档站中，我们会省略「框架」，直接称其为 Modern.js。
+:::
+
+## Modern.js 框架
+
+**Modern.js 框架是一个基于 React 的渐进式 Web 开发框架**。在字节跳动内部，我们将 Modern.js 封装为上层框架，并支撑了数千个 Web 应用的研发。
+
+Modern.js 能为开发者提供极致的**开发体验（Development Experience）**，让应用拥有更好的**用户体验（User Experience）**。
+
+在开发 React 应用过程中，开发者通常需要去为某些功能去设计实现方案，或是使用其他的库、框架来解决这些问题。Modern.js 支持 React 应用所需要的所有配置和工具，并内置**额外的功能和优化**。开发者可以使用 React 构建应用的 UI，然后逐步采用 Modern.js 的功能来解决常见的应用需求，如路由、数据获取、状态管理等。
+
+它主要包含以下特性：
+
+- 🚀 **Rust 构建**：提供双构建工具支持，轻松切换到 Rspack 构建工具，编译飞快。
+- 🪜 **渐进式**：使用最精简的模板创建项目，通过生成器逐步开启插件功能，定制解决方案。
+- 🏠 **一体化**：开发与生产环境 Web Server 唯一，CSR 和 SSR 同构开发，函数即接口的 API 服务调用。
+- 📦 **开箱即用**：默认 TS 支持，内置构建、ESLint、调试工具，全功能可测试。
+- 🌏 **周边生态**：自研状态管理、微前端、模块打包、Monorepo 方案等周边需求。
+- 🕸 **多种路由模式**：包含自控路由、基于文件约定的路由（嵌套路由）等。
+
+## 下一步
+
+如果你希望了解如何使用 Modern.js 框架，可以尝试 [创建第一个应用](/tutorials/first-app/c01-start)，或是阅读 [快速上手](/guides/get-started/quick-start)。

package/docs/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
+? 请选择你想创建的工程类型：Npm 模块
+? 请填写项目名称：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
+? 请选择你想创建的工程类型：Npm 模块
+? 请填写子项目名称：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 后，依然可以和模块类型一样供其他仓库使用。

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

@@ -0,0 +1,271 @@
+---
+sidebar_position: 7
+---
+
+# 自定义提交 commit 信息
+
+Changesets 支持配置 `commit` 为 true 时，在执行 `change` 和 `bump` 命令时自动提交当前变更。
+
+默认的 `commit` 信息由 `@changesets/cli/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 信息。
+
+## 自定义 commit 信息内容
+
+commit 信息分为两种：
+
+- 执行 `change` 命令时自动生成的 commit 信息。
+- 执行 `bump` 命令时自动生成的 commit 信息。
+
+自定义逻辑主要实现两个函数，`getAddMessage` 和 `getVersionMessage`，分别用来定义上述这两种信息。
+
+### getAddMessage
+
+#### Params
+
+- changeset
+
+当前创建的 chagneset 信息
+
+```ts
+type Release = {
+  name: string;
+  type: VersionType;
+};
+
+type Changeset = {
+  summary: string;
+  releases: Array<Release>;
+};
+```
+
+- options
+
+配置 commit 时的配置信息。
+
+> commit 配置为数组时，第二个参数支持传入默认的配置信息，会对应的使用该参数传递。
+
+#### 返回值
+
+commit 信息内容。
+
+#### 默认实现
+
+`@changesets/cli/commit` 默认处理逻辑为以 `docs(changeset):` 开头，commit 信息为 changeset 的 `summary`，并根据传入的 `skipCI` 参数配置添加 [skip ci] 信息。
+
+```ts
+type SkipCI = boolean | 'add' | 'version';
+
+const getAddMessage = async (
+  changeset: Changeset,
+  options: { skipCI?: SkipCI } | null,
+) => {
+  const skipCI = options?.skipCI === 'add' || options?.skipCI === true;
+  return outdent`docs(changeset): ${changeset.summary}${
+    skipCI ? `\n\n[skip ci]\n` : ''
+  }`;
+};
+```
+
+> [outdent](https://www.npmjs.com/package/outdent) 目的是删除模板字符串开头的空格内容，使 commit 信息更符合规范。
+
+### getVersionMessage
+
+#### Params
+
+- releasePlan
+
+```ts
+type VersionType = 'major' | 'minor' | 'patch' | 'none';
+
+type Release = {
+  name: string;
+  type: VersionType;
+};
+
+type Changeset = {
+  id: string;
+  summary: string;
+  releases: Array<Release>;
+};
+
+type ComprehensiveRelease = {
+  name: string;
+  type: VersionType;
+  oldVersion: string;
+  newVersion: string;
+  changesets: string[];
+};
+
+type PreState = {
+  mode: 'pre' | 'exit'; // pre 模式当前状态
+  tag: string; // pre 的类型
+  initialVersions: {
+    [pkgName: string]: string; // 版本升级前包名及版本号信息，Map 格式
+  };
+  changesets: string[]; // 本次升级的 changeset id 列表
+};
+
+type ReleasePlan = {
+  changesets: Changeset[]; // 本次升级的 changeset 列表
+  releases: ComprehensiveRelease[]; // 当前升级的包信息，包含包名称、当前版本、升级后版本、升级类型等
+  preState: PreState | undefined; // 当前如果为 pre 发布，提供相关状态信息
+};
+```
+
+- options
+
+配置 commit 时的配置信息。
+
+> commit 配置为数组时，第二个参数支持传入默认的配置信息，会对应的使用该参数传递。
+
+#### 返回值
+
+commit 信息内容。
+
+#### 默认实现
+
+`@changesets/cli/commit` 默认处理逻辑为：先展示当前需要 release 的包数量，再展示 release 包的名称及新版本号，并根据传入的 `skipCI` 参数配置添加 [skip ci] 信息。
+
+```ts
+const getVersionMessage = async (
+  releasePlan: ReleasePlan,
+  options: { skipCI?: SkipCI } | null,
+) => {
+  const skipCI = options?.skipCI === 'version' || options?.skipCI === true;
+  const publishableReleases = releasePlan.releases.filter(
+    release => release.type !== 'none',
+  );
+  const numPackagesReleased = publishableReleases.length;
+
+  const releasesLines = publishableReleases
+    .map(release => `  ${release.name}@${release.newVersion}`)
+    .join('\n');
+
+  return outdent`
+    RELEASING: Releasing ${numPackagesReleased} package(s)
+
+    Releases:
+    ${releasesLines}
+    ${skipCI ? `\n[skip ci]\n` : ''}
+`;
+};
+```
+
+## 配置
+
+Changesets 配置文件中 `commit` 字段，该字段用于标记是否需要在 `change` 和 `bump` 命令是提交 commit 信息及 commit 信息的获取途径。
+
+该配置可以为 `boolean`，为 true 时使用默认 `@changesets/cli/commit` 格式化 commit 信息。
+
+该配置可以为字符串，直接声明获取 commit 信息模块的模块名称或者路径。
+
+该配置还支持配置数组，数组中第一个元素为获取 commit 信息模块的模块名称或者路径，第二个元素为传入对应函数的参数值，会作为 `getAddMessage` 和 `getVersionMessage` 函数的第二个参数传入。
+
+### 配置相对路径
+
+commit 配置如果为相对路径为 `.changesets` 目录下的相对路径。
+
+例如创建 .changeset/my-commit-config.js 文件，定义如下内容：
+
+```js title=".changeset/my-commit-config.js"
+async function getAddMessage(changeset, options) {}
+
+async function getVersionMessage(releasePlan, options) {}
+
+module.exports = {
+  getAddMessage,
+  getVersionMessage,
+};
+```
+
+commit 配置为 ./my-commit-config.js 即可:
+
+```json title=".changesets/config.json"
+{
+  "changelog": "./my-commit-config.js",
+   ...
+}
+```
+
+### 使用模块工程方案
+
+自定义 commit 还可以使用模块工程方案进行管理，提供通用方案。
+
+自定义 Changelog 还可以使用模块工程方案进行管理，提供通用方案。
+
+#### 使用 `npx @modern-js/create` 创建模块工程方案。
+
+```md
+? 请选择你想创建的工程类型：Npm 模块
+? 请填写项目名称：custom-commit
+? 请选择开发语言：TS
+? 请选择包管理工具：pnpm
+```
+
+#### 实现自定义内容。
+
+```ts title="src/index.ts"
+export async function getAddMessage() {}
+
+export async function getVersionMessage() {}
+```
+
+#### 将模块发布到 NPM。
+
+#### 在目标仓库根目录安装对应模块，例如 custom-commit。
+
+#### 配置 changeset 的 commit 配置为包名称。
+
+```json title="package.json"
+{
+  "changelog": "custom-commit",
+   ...
+}
+```
+
+### 使用 Monorepo 工程方案
+
+如果你当前仓库为 Monorepo 工程方案，可以直接使用模块子项目进行管理。
+
+#### 执行 `pnpm run new` 创建模块子项目。
+
+```md
+? 请选择你想创建的工程类型：Npm 模块
+? 请填写子项目名称：custom-commit
+? 请填写子项目目录名称：custom-commit
+? 请选择开发语言：TS
+```
+
+#### 实现自定义内容。
+
+```ts title="src/index.ts"
+export async function getAddMessage() {}
+
+export async function getVersionMessage() {}
+```
+
+#### 在 Monorepo 根目录添加子项目模块依赖，例如 custom-commit。
+
+```json title="package.json"
+{
+  "devDependencies": {
+    "custom-commit": "workspace: *",
+    ...
+  }
+}
+```
+
+#### 配置 changeset 的 commit 配置为包名称。
+
+```json title=".changesets/config.json"
+{
+  "commit": "custom-commit",
+   ...
+}
+```
+
+该模块发布到 NPM 后，依然可以和模块类型一样供其他仓库使用。