@modern-js/main-doc 2.7.0 → 2.9.0

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

@@ -0,0 +1,164 @@
+---
+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: web-infra-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: web-infra-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 流程。

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

@@ -0,0 +1,259 @@
+---
+sidebar_position: 8
+---
+
+# 自定义 Release Note 格式
+
+Modern.js 提供了 `modern gen-release-note` 命令，支持通过当前存在的 changeset 和 git commit 信息自动生成 Release Note 信息，在发布命令执行之前，可以通过执行该命令生成本次发布的 Release Note。
+
+默认生成的 Release Note 格式为：
+
+```markdown
+[[#1220](https://github.com/web-infra-dev/modern.js/pull/1220)] feat: support bff operators -- Ming
+```
+
+根据 commit 信息获取 changeset 的 Pull Request ID，并生成 Github 的链接，内容为 changeset 的 changelog 信息和作者信息。
+
+当默认生成 Release Note 逻辑不能满足需求时，支持自定义 Release Note 格式。
+
+## 信息
+
+### 自定义 Release Note 所需信息
+
+生成 Release Note 信息需要先收集一些信息，比如 commit ID、Pull Request ID、commit message 等等。
+
+该逻辑可通过 `getReleaseInfo` 函数实现。
+
+#### getReleaseInfo
+
+##### Params
+
+- commit
+
+类型： string;
+
+当前 changeset 对应的 commit message 信息。
+
+执行 `git log --pretty=format:%h--%s--%an .changeset/${changeset.id}.md` 的结果。
+
+- commitObj
+
+初步解析 commit 获取基本信息。
+
+```ts
+interface Commit {
+  id: string; // commit id
+  type: 'feature' | 'fix'; // commit 类型，默认通过开头字符串如果为 fix，类型为 fix，其他为 feature
+  repository?: string; // 参数传入的 repo 信息或者 package.json 中定义的 repository 信息
+  pullRequestId?: string;
+  author?: string;
+  message: string; // commit message
+  summary: string; // changeset summary
+  [key: string]: string | undefined;
+}
+```
+
+##### 返回值
+
+commitObj， 补充后完整的 commit 对象。
+
+##### 默认实现
+
+Modern.js 的默认实现为：根据 commit 信息拆分出 Pull Request ID 和作者，加入到 commitObj 中。
+
+```ts
+function getReleaseInfo(commit: string, commitObj: Commit) {
+  const commitRegex = /(.*)\(#(\d*)\)/;
+
+  const [, message, author] = commit.split('--');
+
+  commitObj.author = author;
+
+  if ((message || commitObj.summary).match(commitRegex)) {
+    const [, messageShort, pullRequestId] = (
+      message || commitObj.summary
+    ).match(commitRegex)!;
+    commitObj.pullRequestId = pullRequestId;
+    commitObj.message = messageShort.trim();
+  }
+
+  return commitObj;
+}
+```
+
+### 使用获取的信息生成 Release Note
+
+根据 `getReleaseInfo` 中获取的 commit 对象信息，生成对应的 Release Note。
+
+该逻辑可通过 `getReleaseNoteLine` 函数实现。
+
+#### getReleaseNoteLine
+
+##### Params
+
+- commit
+
+类型和上述 commitObj 类型一致。
+
+##### 返回值
+
+生成的 Release Note。
+
+##### 默认实现
+
+Modern.js 的默认实现为：
+
+```ts
+function formatSummary(summary: string, pullRequestId?: string) {
+  const [firstLine, ...futureLines] = summary
+    .split('\n')
+    .map(l => l.trimRight());
+
+  let returnVal = firstLine;
+
+  if (futureLines.length > 0) {
+    if (pullRequestId) {
+      returnVal = `\n\n  ${returnVal}`;
+    } else {
+      returnVal = `\n  ${returnVal}`;
+    }
+    returnVal += `\n\n  ${futureLines
+      .filter(l => Boolean(l))
+      .map(l => l)
+      .join('\n\n')}`;
+  }
+  return returnVal;
+}
+
+export async function getReleaseNoteLine(
+  commit: Commit,
+  customReleaseNoteFunction?: CustomReleaseNoteFunction,
+) {
+  if (customReleaseNoteFunction?.getReleaseNoteLine) {
+    return customReleaseNoteFunction.getReleaseNoteLine(commit);
+  }
+
+  const { repository, pullRequestId, summary } = commit;
+  if (pullRequestId && repository) {
+    return `- [#${pullRequestId}](https://github.com/${repository}/pull/${pullRequestId}) ${formatSummary(
+      summary,
+      pullRequestId,
+    )}\n`;
+  }
+  if (pullRequestId) {
+    return `#${pullRequestId} ${formatSummary(summary, pullRequestId)}\n`;
+  }
+  return `${formatSummary(summary, pullRequestId)}\n`;
+}
+```
+
+## 使用自定义模块
+
+`gen-release-note` 命令支持 `--custom` 参数，该参数可传入自定义 release note 模块的模块名称或者路径。
+
+### 配置相对路径
+
+custom 参数值如果为相对路径为**项目跟目录**。
+
+例如创建 `scripts/my-release-note-config.js` 文件，定义如下内容：
+
+```ts title="scripts/my-release-note-config.js"
+function getReleaseInfo(commit, commitObj) {
+  return commitObj;
+}
+
+function getReleaseNoteLine(commit) {}
+
+module.exports = {
+  getReleaseInfo,
+  getReleaseNoteLine,
+};
+```
+
+执行下面命令：
+
+```bash
+pnpm run gen-release-note -- --custom ./scripts/my-release-note-config.js
+```
+
+也可以把命令参数直接定义到 package.json 中：
+
+```json title="package.json"
+{
+    "scripts": {
+        ...
+        "gen-release-note": "modern gen-release-note --custom ./scripts/my-release-note-config.js"
+    },
+    ...
+}
+```
+
+直接执行命令 `pnpm run gen-release-note` 即可。
+
+### 使用模块工程方案
+
+custom 参数值还可以使用模块工程方案进行管理，提供通用方案。
+
+1. 使用 npx @modern-js/create 创建模块工程方案。
+
+```md
+? 请选择你想创建的工程类型：Npm 模块
+? 请填写项目名称：custom-release-note
+? 请选择开发语言：TS
+? 请选择包管理工具：pnpm
+```
+
+2. 实现自定义内容。
+
+```ts title="src/index.ts"
+export function getReleaseInfo() {}
+
+export function getReleaseNoteLine() {}
+```
+
+3. 将模块发布到 NPM。
+4. 在目标仓库根目录安装对应模块，例如 `custom-release-note`。
+5. 执行 gen-release-note 命令添加 custom 参数
+
+```bash
+pnpm run gen-release-note -- --custom custom-release-note
+```
+
+### 使用 Monorepo 工程方案
+
+如果你当前仓库为 Monorepo 工程方案，可以直接使用模块子项目进行管理。
+
+1. 执行 `pnpm run new` 创建模块子项目
+
+```md
+? 请选择你想创建的工程类型：Npm 模块
+? 请填写子项目名称：custom-release-note
+? 请填写子项目目录名称：custom-release-note
+? 请选择开发语言：TS
+```
+
+2. 实现自定义内容。
+
+```ts title="src/index.ts"
+export function getReleaseInfo() {}
+
+export function getReleaseNoteLine() {}
+```
+
+3. 在 Monorepo 根目录添加子项目模块依赖，例如 `custom-release-note`。
+
+```json title="package.json"
+{
+  "devDependencies": {
+    "custom-release-note": "workspace: *",
+    ...
+}
+```
+
+4. 执行 `gen-release-note` 命令添加 `--custom` 参数
+
+```bash
+pnpm run gen-release-note -- --custom custom-release-note
+```
+
+该模块发布到 NPM 后，依然可以和模块类型一样供其他仓库使用。

package/docs/zh/guides/topic-detail/framework-plugin/plugin-api.mdx

@@ -0,0 +1,117 @@
+---
+title: 插件 API
+sidebar_position: 6
+---
+# 插件 API
+
+插件的 `setup` 函数会接收一个 `api` 入参，你可以调用 api 上提供的一些方法来获取到配置、应用上下文等信息。
+
+```ts
+import type { CliPlugin } from '@modern-js/core';
+
+export default (): CliPlugin => ({
+  name: 'my-plugin',
+
+  setup(api) {
+    // 获取应用原始配置
+    const config = api.useConfigContext();
+    // 获取应用运行上下文
+    const appContext = api.useAppContext();
+    // 获取解析之后的最终配置
+    const resolvedConfig = api.useResolvedConfigContext();
+  },
+});
+```
+
+## API
+
+### useConfigContext
+
+用于获取应用原始配置。
+
+```ts
+const useConfigContext: () => UserConfig;
+
+interface UserConfig {
+  source?: SourceConfig;
+  output?: OutputConfig;
+  server?: ServerConfig;
+  dev?: DevConfig;
+  deploy?: DeployConfig;
+  tools?: ToolsConfig;
+  plugins?: PluginConfig;
+  runtime?: RuntimeConfig;
+  runtimeByEntries?: RuntimeByEntriesConfig;
+}
+```
+
+具体配置字段的意义请参考【[配置](/configure/app/usage)】。
+
+### useAppContext
+
+用于获取应用运行上下文。
+
+```ts
+const useAppContext: () => IAppContext;
+
+interface IAppContext {
+  appDirectory: string;
+  configFile: string | false;
+  ip?: string;
+  port?: number;
+  distDirectory: string;
+  packageName: string;
+  srcDirectory: string;
+  sharedDirectory: string;
+  nodeModulesDirectory: string;
+  internalDirectory: string;
+  plugins: {
+    cli?: any;
+    server?: any;
+  }[];
+  entrypoints: Entrypoint[];
+  serverRoutes: ServerRoute[];
+  htmlTemplates: HtmlTemplates;
+}
+```
+
+### useResolvedConfigContext
+
+用于获取解析之后的最终配置。
+
+```ts
+const useResolvedConfigContext: () => NormalizedConfig;
+
+interface NormalizedConfig {
+  source: NormalizedSourceConfig;
+  output: OutputConfig;
+  server: ServerConfig;
+  dev: DevConfig;
+  deploy: DeployConfig;
+  tools: NormalizedToolsConfig;
+  plugins: PluginConfig;
+  runtime: RuntimeConfig;
+  runtimeByEntries?: RuntimeByEntriesConfig;
+  _raw: UserConfig;
+}
+```
+
+具体配置字段的意义请参考【[配置](/configure/app/usage)】。
+
+### useHookRunners
+
+用于获取 Hooks 的执行器，并触发特定的 Hook 执行。
+
+```ts
+import type { CliPlugin } from '@modern-js/core';
+
+export default (): CliPlugin => ({
+  name: 'my-plugin',
+
+  async setup(api) {
+    const hookRunners = api.useHookRunners();
+    // 触发 afterBuild Hook
+    await hookRunners.afterBuild();
+  },
+});
+```

package/docs/zh/guides/topic-detail/generator/plugin/develop.mdx

@@ -0,0 +1,125 @@
+---
+sidebar_position: 3
+---
+
+# 如何开发生成器插件
+
+## 创建项目
+
+Modern.js 提供了生成器插件用于创建开发项目，可直接执行以下命令创建:
+
+```bash
+npx @modern-js/create plugin --plugin @modern-js/generator-plugin-plugin
+```
+
+插件类型不同，会提问不同的问题，可根据需求选择插件类型
+
+### 扩展工程方案
+
+```
+? 请选择你想创建的工程类型：Npm 模块
+? 请选择项目场景：生成器插件
+? 插件包名：plugin
+? 请选择开发语言：TS
+? 请选择包管理工具：pnpm
+? 插件类型：扩展
+? 插件基础类型：应用
+```
+
+### 创建工程方案场景
+
+```
+? 请选择你想创建的工程类型：Npm 模块
+? 请选择项目场景：生成器插件
+? 插件包名：plugin
+? 请选择开发语言：TS
+? 请选择包管理工具：pnpm
+? 插件类型：自定义
+? 插件关键字：mobile-app
+? 插件展示名称：移动应用
+? 插件基础类型：应用
+```
+
+创建项目命令执行完成后，会对应的生成一个开发生成器插件的项目，`package.json` 中也会根据你的选择对应的生成 `meta` 信息。
+
+:::info
+生成器插件开发可参考 `@modern-js/generator-plugin-plugin` [源码地址](https://github.com/web-infra-dev/modern.js/tree/main/packages/generator/plugins/generator-plugin)
+
+:::
+
+## 开发插件逻辑
+
+在 `src/index.ts` 中完成插件逻辑开发。
+
+插件默认导出一个函数，函数参数为 `context`，`context` 上提供一些方法可直接对当前项目进行操作。
+
+简单介绍一下提供的方法，完整的 API 列表可查看[生成器插件 API](/guides/topic-detail/generator/plugin/api/introduce)。
+
+### 自定义输入
+
+- addInputBefore
+
+在默认的输入前添加输入，比如在`选择包管理工具`问题前添加问题，具体 Modern.js 每个问题的配置可查看[工程方案配置](/guides/topic-detail/generator/config/common)。
+
+```ts
+context.addInputBefore('input2', {
+  type: 'object',
+  properties: {
+    'input1.2': {
+      type: 'string',
+      title: 'input1.2',
+    },
+  },
+});
+```
+
+- setInput
+
+设置已经存在问题的属性
+
+```ts
+context.setInput('test', 'type', 'number');
+context.setInput('test', 'enum', [{ value: 'option1', label: '选项一' }]);
+```
+
+### onForged
+
+工程方案类型文件相关操作执行完成后钩子，多个扩展产检将按照 `plugin` 参数顺序依次执行其 `onForged` 函数。
+
+`onForged` 参数是一个回调函数，函数参数为 `api` 和 `input`。
+
+`api` 上会提供一些文件操作相关的方法，可在该钩子中对当前的模板文件进行操作。
+
+`input` 为当前用户输入，可用于获取用户当前的输入信息及配置信息。
+
+当需要新的模板文件时，可直接在 `templates` 目录添加，在 `onForged` 函数中可直接对 `templates` 目录文件进行操作，比如下方的 `addFile` 中 `templateFile` 参数就为 `templates` 目录下的文件。这里不需要显示的声明 `templates`，直接写相对于 `templates` 的相对路径即可。
+
+`onForged` 中支持的 API 函数也可参考 [生成器插件 API](/guides/topic-detail/generator/plugin/api/hook/onForged)。
+
+```ts
+context.onForged(async (api: ForgedAPI, input: Record<string, unknown>) => {
+  const { language } = input;
+  api.addFile({
+    type: FileType.Text,
+    file: `src/index.${language as string}`,
+    templateFile: `index.${language as string}.handlebars`,
+    force: true,
+  });
+});
+```
+
+### afterForged
+
+`onForged` 函数执行完成后钩子，这里主要可进行安装依赖，Git 操作等。
+
+如果你的工程方案是基于 Modern.js 提供的三种工程方案进行的，这个钩子函数是可以不需要的。默认的工程方案中会自动包含安装依赖、提交代码逻辑。
+
+生成器插件还支持了一种自定义的 `custom` 类型，这种类型只提供了少量的开发层面的最佳实践的代码，比如 `.gitignore`、`.editorConfig` 等文件，这时则需要在 `afterForged` 函数中手动补充安装依赖和 Git 操作逻辑。
+
+`afterForged` 参数也是一个回调函数，函数参数为 `api` 和 `input`。
+
+`api` 上会提供一些 npm、Git 等方法，可在该钩子中进行安装依赖，Git 操作。
+
+`input` 为当前用户输入，可用于获取用户当前的输入信息及配置信息。
+
+`afterForged` 中支持的 API 函数也可参考 [生成器插件 API](/guides/topic-detail/generator/plugin/api/hook/afterForged)。

package/docs/zh/guides/topic-detail/model/faq.mdx

@@ -0,0 +1,41 @@
+---
+sidebar_position: 13
+title: 常见问题
+---
+
+# 常见问题
+
+## 浏览器兼容性
+
+Reduck 的编译构建产物默认使用 ES6 语法，如果你需要支持更低版本的浏览器，请将 `@modern-js-reduck` 命名空间下的所有包加入到应用的编译过程。
+
+:::info 补充信息
+Reduck 使用的 [`@babel/preset-env`](https://babeljs.io/docs/en/babel-preset-env) 的详细[配置](https://github.com/web-infra-dev/reduck/blob/main/common/config.js#L10~L17)。
+
+:::
+
+## 微前端子应用 Model 访问主应用 Model
+
+微前端子应用 Model 访问主应用 Model 时，如果该 **Model** 在主应用尚未挂载，会自动挂载到子应用上。
+
+示例：
+
+```ts
+import { useModel } from '@modern-js/runtime/model';
+import parentModel from '@MasterApp/models/todoModel';
+
+function SubModelApp() {
+  const [state, actions] = useModel(parentModel);
+
+  return <div>...</div>;
+}
+```
+
+![微前端通信流程图](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/mf-communicate.svg)
+
+为了避免意外降级挂载，建议将主应用所需要共享的 Model 预先挂载：
+
+```ts
+// App 是主应用的入口组件，sharedModel1、sharedModel2 是需要共享的 Model。
+App.models = [sharedModel1, sharedModel2];
+```