@modern-js/main-doc 2.8.0 → 2.9.0

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/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/monorepo/create-sub-project.mdx

@@ -0,0 +1,67 @@
+---
+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 应用
+  Web 应用（测试）
+  Npm 模块
+  Npm 模块（内部）
+```
+
+:::info
+「应用」与「应用（测试）」都是「应用」类型的项目，区别是「应用」类型的子项目会创建在 `./apps` 目录下，而 「应用（测试）」类型的子项目会创建在 `./examples` 目录下。
+
+:::
+
+:::info
+「模块」与「模块（内部）」都是「模块」类型的项目，区别之一是「模块」类型的子项目会创建在 `./packages` 目录下，而「模块（内部）」类型的子项目会创建在 `./features` 目录下。
+
+对于「模块」类型的子项目允许被发布到外部（例如 npm)，而对于「模块（内部）」的子项目则可以在应用项目中直接使用其源码（该特性是「模块」项目不具备的，应用项目对于「模块（内部）」子项目做了特殊处理），因此这类子项目不需要发布到外部。
+
+:::
+
+然后根据不同的需求选择对应的类型项目选项，选择之后便开始出现对应子项目类型的问题和选项。例如选择「应用」后会出现：
+
+```
+? 请选择你想创建的工程类型：Web应用
+? 请填写子项目名称
+```
+
+当完成所有生成器问题之后，便开始进行项目的创建和项目依赖的下载。当创建成功之后，可以看到类似以下内容：
+
+```
+[INFO] 依赖自动安装成功
+[INFO] 创建成功！
+可在新项目的目录下运行以下命令：
+pnpm run dev          # 按开发环境的要求，运行和调试项目
+pnpm run build        # 按生产环境的要求，构建项目
+pnpm run serve        # 按生产环境的要求，运行项目
+pnpm run lint         # 检查和修复所有代码
+pnpm run new          # 继续创建更多项目要素，比如应用入口
+```

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

@@ -0,0 +1,179 @@
+---
+sidebar_position: 3
+---
+
+# 子项目联调
+
+本章将要介绍如何在 Monorepo 下进行子项目之间的联调使用。
+
+## 准备工作
+
+按照 [「创建子项目」](/guides/topic-detail/monorepo/create-sub-project) 章节的介绍（如果还没有看过，可以先了解一下），我们首先创建以下三个子项目：
+
+- 一个「应用」子项目
+- 一个「模块（内部）」子项目
+- 一个「模块」子项目
+
+执行 `pnpm run new`，并按照如下进行选择：
+
+**「应用」子项目：**
+
+```
+? 请选择你想创建的工程类型：Web 应用
+? 请填写子项目名称：app
+? 请填写子项目目录名称：app
+? 请选择开发语言：TS
+```
+
+**「模块（内部）」子项目：**
+
+```
+? 请选择你想创建的工程类型：Npm 模块（内部）
+? 请填写子项目名称：internal-lib
+? 请填写子项目目录名称：internal-lib
+? 请选择开发语言：TS
+```
+
+**「模块」子项目：**
+
+```
+? 请选择你想创建的工程类型：Npm 模块
+? 请填写子项目名称：components
+? 请填写子项目目录名称：components
+? 请选择开发语言：TS
+```
+
+创建成功后，会得到以下项目：
+
+- `./apps/app`
+- `./packages/components`
+- `./features/internal-lib`
+
+然后修改一下默认的代码和新增文件：
+
+**重命名 `./pakcages/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>
+  );
+}
+```
+
+**新增 `./pakcages/components/src/index.css`**
+
+```css
+.log {
+  color: gray;
+}
+```
+
+**修改 `./features/internal-lib/src/index.ts`**
+
+```tsx
+export default function (text: string) {
+  return text.toUpperCase();
+}
+```
+
+**修改 `./apps/app/src/App.tsx`**
+
+```tsx
+import { Switch, Route } from '@modern-js/runtime/router';
+import formatString from 'internal-lib';
+import Comp from 'components';
+
+import './App.css';
+
+const App = () => (
+  <Switch>
+    <Route exact={true} path="/">
+      <div className="container-box">
+        <Comp text={formatString('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` 子项目下分别执行：
+
+```
+pnpm add components
+```
+
+以及
+
+```
+pnpm add internal-lib -D
+```
+
+:::info
+注意这里将 internal-lib 作为 `apps/app` 项目的开发依赖，因为在构建环境会被打包到构建产物中。
+
+:::
+
+将 `packages/components` 与 `features/internal-lib` 子项目加入到应用的依赖列表当中。
+
+执行成功后，在 `apps/app/package.json` 会发生如下变化：
+
+```json
+{
+  "dependencies": {
+++  "components": "workspace:^0.1.0"
+  },
+  "devDependencies": {
+++  "internal-lib": "workspace:^0.1.0"
+  },
+}
+```
+
+:::info 补充信息
+`workspace:^0.1.0` 是一种 PNPM 提供的 [Workspace 协议](https://pnpm.io/workspaces#workspace-protocol-workspace)。
+
+:::
+
+当依赖安装成功之后，我们还需要将 `packages/components` 进行构建，因为需要使用其构建产物。
+
+到此为止，`app/apps` 应用子项目可以正常的运行了。在修改 `features/internal-lib` 的源码，或者修改 `packages/components` 的源码并构建之后都会触发应用子项目的热更新。
+
+## 在使用 Yarn 的 Monorepo 中进行项目联调
+
+在 Yarn 的 Monorepo 项目中，默认情况下可以直接在 `apps/app` 应用项目中直接使用组件项目和内部模块项目。
+
+:::info 补充信息
+之所以可以直接在应用中使用使用组件项目和内部模块项目，是因为 Yarn 将这些子项目模块提升到了顶层的 `node_modules`内。
+
+:::
+
+但是由于组件 `components` 是非内部模块，因此建议在 `apps/app/package.json` 中进行依赖声明：
+
+```json
+{
+  "dependencies": {
+++  "components": "0.1.0"
+  },
+}
+```

package/docs/zh/index.md

@@ -0,0 +1,4 @@
+---
+pageType: home
+---
+# Modern.js - 基于 React 的渐进式 Web 开发框架

package/en/configure/app/dev/asset-prefix.mdx

@@ -8,6 +8,6 @@ sidebar_label: assetPrefix
 This config is provided by Modern.js Builder, more detail can see [dev.assetPrefix](https://modernjs.dev/builder/en/api/config-dev.html#devassetprefix).
 :::
 
-import Main from '@modern-js/builder-doc/docs/en/config/dev/assetPrefix.md'
+import Main from '@modern-js/builder-doc/docs/en/config/dev/assetPrefix.md';
 
 <Main />

package/en/configure/app/dev/before-start-url.mdx

@@ -8,6 +8,6 @@ sidebar_label: beforeStartUrl
 This config is provided by Modern.js Builder, more detail can see [dev.beforeStartUrl](https://modernjs.dev/builder/en/api/config-dev.html#devbeforestarturl).
 :::
 
-import Main from '@modern-js/builder-doc/docs/en/config/dev/beforeStartUrl.md'
+import Main from '@modern-js/builder-doc/docs/en/config/dev/beforeStartUrl.md';
 
 <Main />

package/en/configure/app/dev/hmr.mdx

@@ -8,6 +8,6 @@ sidebar_label: hmr
 This config is provided by Modern.js Builder, more detail can see [dev.hmr](https://modernjs.dev/builder/en/api/config-dev.html#devhmr).
 :::
 
-import Main from '@modern-js/builder-doc/docs/en/config/dev/hmr.md'
+import Main from '@modern-js/builder-doc/docs/en/config/dev/hmr.md';
 
 <Main />

package/en/configure/app/dev/host.mdx

@@ -8,6 +8,6 @@ sidebar_label: host
 This config is provided by Modern.js Builder, more detail can see [dev.host](https://modernjs.dev/builder/en/api/config-dev.html#devhost).
 :::
 
-import Main from '@modern-js/builder-doc/docs/en/config/dev/host.md'
+import Main from '@modern-js/builder-doc/docs/en/config/dev/host.md';
 
 <Main />

package/en/configure/app/dev/https.mdx

@@ -8,6 +8,6 @@ sidebar_label: https
 This config is provided by Modern.js Builder, more detail can see [dev.https](https://modernjs.dev/builder/en/api/config-dev.html#devhttps).
 :::
 
-import Main from '@modern-js/builder-doc/docs/en/config/dev/https.md'
+import Main from '@modern-js/builder-doc/docs/en/config/dev/https.md';
 
 <Main />

package/en/configure/app/dev/port.mdx

@@ -8,6 +8,6 @@ sidebar_label: port
 This config is provided by Modern.js Builder, more detail can see [dev.port](https://modernjs.dev/builder/en/api/config-dev.html#devport).
 :::
 
-import Main from '@modern-js/builder-doc/docs/en/config/dev/port.md'
+import Main from '@modern-js/builder-doc/docs/en/config/dev/port.md';
 
 <Main />

package/en/configure/app/dev/progress-bar.mdx

@@ -8,6 +8,6 @@ sidebar_label: progressBar
 This config is provided by Modern.js Builder, more detail can see [dev.progressBar](https://modernjs.dev/builder/en/api/config-dev.html#devprogressbar).
 :::
 
-import Main from '@modern-js/builder-doc/docs/en/config/dev/progressBar.md'
+import Main from '@modern-js/builder-doc/docs/en/config/dev/progressBar.md';
 
 <Main />