npm - @modern-js/main-doc - Versions diffs - 2.7.0 → 2.9.0 - Mend

@modern-js/main-doc 2.7.0 → 2.9.0

Files changed (1123) hide show

package/zh/guides/get-started/introduction.mdx DELETED Viewed

@@ -1,31 +0,0 @@
----
-title: 介绍
-sidebar_position: 1
----
-# Modern.js 介绍
-**Modern.js** 是基于 React 的渐进式现代 Web 开发框架。
-框架内置多种开箱即用的开发工具，拥有极致的构建性能，支持零配置的渲染范式切换，一体化的 API 调用。并从三种工程方案出发（应用工程方案、模块工程方案，Monorepo 工程方案），支持全链路的前端研发。
-Modern.js 是字节跳动的底层前端研发框架，已经直接或间接的服务上千个应用，包括中后台、PC Web、H5 等多种应用场景。框架覆盖完整的生命周期，拥有完善的插件体系，提供高度定制能力。支持通过生成器插件自定义业务线专属的工程方案，定制各种功能扩展和业务需求，帮助开发者更快速的搭建应用。
-## 为什么使用 Modern.js
-Modern.js 能为开发者提供极致的**开发体验（Development Experience）**，让应用拥有更好的**用户体验（User Experience）**。
-在开发 React 应用过程中，开发者通常需要去为某些功能去设计实现方案，或是使用其他的库、框架来解决这些问题。Modern.js 支持 React 应用所需要的所有配置和工具，并内置**额外的功能和优化**。开发者可以使用 React 构建应用的 UI，然后逐步采用 Modern.js 的功能来解决常见的应用需求，如路由、数据获取、状态管理等。
-它主要包含以下特点：
-- 🪜 **渐进式**：使用最精简的模板创建项目，通过生成器逐步开启插件功能，定制解决方案。
-- 🏠 **一体化**：开发与生产环境 Web Server 唯一，CSR 和 SSR 同构开发，函数即接口的 API 服务调用。
-- 📦 **开箱即用**：默认 TS 支持，内置构建、ESLint、调试工具，全功能可测试。
-- 🌏 **周边生态**：自研状态管理、微前端、模块打包、Monorepo 方案等周边需求。
-- 🕸 **多种路由模式**：包含自控路由、基于文件约定的路由（嵌套路由）等。
-- 🚀 **独立构建核心**：支持多种打包工具，深度优化构建产物。
-## 下一步
-如果你希望了解如何使用 Modern.js，可以尝试 [创建第一个应用](/tutorials/first-app/c01-start)，或是阅读 [快速上手](/guides/get-started/quick-start)。

package/zh/guides/topic-detail/changesets/changelog.mdx DELETED Viewed

@@ -1,238 +0,0 @@
----
-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 后，依然可以和模块类型一样供其他仓库使用。

package/zh/guides/topic-detail/changesets/commit.mdx DELETED Viewed

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

package/zh/guides/topic-detail/changesets/github.mdx DELETED Viewed

@@ -1,164 +0,0 @@
----
-sidebar_position: 9
----
-# 使用 Github 相关工具
-## BOT
-在 Github 上，Changesets 提供了机器人用于检测当前 Pull Request 是否存在 changeset，并提供了 UI 界面添加和修改 changeset。
-### 安装
-点击进入[链接](https://github.com/apps/changeset-bot)，右上角选择安装，确认即可安装成功。
-![安装机器人](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-install-bot.png)
-### 配置
-安装成功后，即可进入配置页面，根据需求选择应用仓库即可。
-![配置机器人](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-config-bot.png)
-### 使用
-配置完成后，该机器人将会自动 check 每个 Pull Request 是否添加了 changeset，并通过回复的方式给到提示信息。
-#### 未添加 changeset
-![未添加 changeset 状态](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-bot-no-changeset.png)
-可在仓库执行 `pnpm run change` 添加 changeset，也可直接点击下方第二个链接填写 changeset。
-#### 已添加 changeset
-![已添加 changeset 状态](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-bot-exist-changeset.png)
-可点击下方链接修改和添加新的 changeset。
-#### 不需要 changeset
-可直接忽略未添加时的提示信息，它不会造成 Pull Request 不能合并的问题。
-## Action
-### 自动创建 Release Pull Request
-Modern.js 提供了自动创建发版 Pull Request 的 Github Action，提供基于选择的分支自动执行 bump 操作，更新 lock 文件及创建 Pull Request 操作。
-### 使用
-在仓库中创建 `.github/workflows/release-pull-request.yml` 文件，填入以下内容：
-```yaml
-name: Release Pull Request
-on:
-  workflow_dispatch:
-    inputs:
-      version:
-        description: 'Release Version(v1.0.0)'
-        required: true
-jobs:
-  release:
-    name: Create Release Pull Request
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout Repo
-        uses: actions/checkout@master
-        with:
-          # This makes Actions fetch only one branch to release
-          fetch-depth: 100
-      - name: Create Release Pull Request
-        uses: modern-js-dev/actions@main
-        with:
-          # this expects you to have a script called release which does a build for your packages and calls changeset publish
-          versionNumber: ${{ github.event.inputs.version }}
-          type: 'pull request'
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          REPOSITORY: ${{ github.repository }}
-          REF: ${{ github.ref }}
-```
-将 Workflow 合并到主分支后，进入 Github 仓库对应的 Action 页面，选择 Release Pull Request：
-![Release Pull Request Action](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/action-pull-request.png)
-选择本次发布的分支并填入版本号，版本号格式推荐 v1.0.0，点击 Run workflow 按钮：
-![Run Release Pull Request](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/run-pull-request-action.png)
-workflow 运行完成后将自动创建 `Release-${version}` 的 Pull Request，自动完成 `bump` changeset 相关版本号并更新 lock 文件，Pull Request 的内容为执行 `gen-release-note` 命令自动生成的 Release Note。
-![Release Pull Request](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/release-pull-request.png)
-### 自动 Release
-Modern.js 提供了自动创建发版 Pull Request 的 Github Action，提供基于选择的分支自动执行 release 操作，将包发布到 NPM 上。
-#### 使用
-在仓库中创建 `.github/workflows/release.yml` 文件，填入以下内容：
-```yaml
-name: Release
-on:
-  workflow_dispatch:
-    inputs:
-      version:
-        type: choice
-        description: 'Release Version(canary, alpha, pre, latest)'
-        required: true
-        default: 'canary'
-        options:
-          - canary
-          - alpha
-          - pre
-          - latest
-      branch:
-        description: 'Release Branch(confirm release branch)'
-        required: true
-        default: 'main'
-jobs:
-  release:
-    name: Release
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout Repo
-        uses: actions/checkout@master
-        with:
-          # This makes Actions fetch only one branch to release
-          fetch-depth: 1
-      - name: Release
-        uses: modern-js-dev/actions@main
-        with:
-          # this expects you to have a script called release which does a build for your packages and calls changeset publish
-          version: ${{ github.event.inputs.version }}
-          branch: ${{ github.event.inputs.branch }}
-          type: 'release'
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-          REPOSITORY: ${{ github.repository }}
-          REF: ${{ github.ref }}
-```
-配置仓库的 NPM_TOKEN:
-![配置 Token](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/github-set-npm-token.png)
-将 Workflow 合并到主分支后，进入 Github 仓库对应的 Action 页面，选择 Release：
-![Release Action](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/release-action.png)
-选择分支名称和发布版本类型，点击 Run workflow 按钮：
-![Run Release Action](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/run-release-workflow.png)
-Workflow 将自动完成仓库 build 和发布到 NPM 流程。