@modern-js/main-doc 2.8.0 → 2.10.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/framework-plugin/plugin-api.mdx

@@ -0,0 +1,118 @@
+---
+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;
+  deploy?: DeployConfig;
+  // ...other fields
+}
+```
+
+具体配置字段的意义请参考 [配置](/configure/app/usage)。
+
+:::tip
+该方法获取到的是只读配置，不可修改。如果需要修改配置，请使用 [config hook](/guides/topic-detail/framework-plugin/hook-list.html#config)。
+:::
+
+### useResolvedConfigContext
+
+用于获取被解析、合并之后的最终配置。
+
+```ts
+const useResolvedConfigContext: () => NormalizedConfig;
+
+interface NormalizedConfig {
+  source: NormalizedSourceConfig;
+  output: NormalizedOutputConfig;
+  server: NormalizedServerConfig;
+  deploy: NormalizedDeployConfig;
+  _raw: UserConfig; // 原始配置对象
+  // ...other fields
+}
+```
+
+配置字段的完整内容请参考 [配置](/configure/app/usage)。
+
+:::tip
+该方法获取到的是只读配置，不可修改。如果需要修改配置，请使用 [config hook](/guides/topic-detail/framework-plugin/hook-list.html#config)。
+:::
+
+### 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;
+}
+```
+
+### 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/codesmith/api/fs.mdx

@@ -0,0 +1,54 @@
+---
+sidebar_position: 3
+---
+
+# @modern-js/codesmith-api-fs
+
+微生成器中文件操作的 API 封装，提供渲染单个模板文件和文件夹的方法。FsAPI 通常用于处理二进制文件或者不能使用 handlebars、ejs 处理的模板文件。
+
+## 使用姿势
+
+```ts
+import { FsAPI } from '@modern-js/codesmith-api-fs';
+
+export default async (context: GeneratorContext, generator: GeneratorCore) => {
+  const fsApi = new FsAPI(generator);
+  await fsApi.renderFile(
+     material.get('templates/a.js'),
+     target: 'b.js'
+   );
+}
+```
+
+- 创建 FsAPI 实例，参数为微生成器函数参数的 generator，具体介绍请看微生成器项目组成 。
+- 调用其实例上 API 即可。
+
+## API
+
+### renderFile
+
+渲染单个模板文件。
+
+参数：
+
+- resource: `FsResource` 模板文件资源，通过 `context.materials.get(<filename>)` 使用。
+- target: `string` 目标文件路径名称。
+
+### renderDir
+
+渲染模板文件夹。
+
+参数：
+
+- material: `FsMaterial` 当前微生成器执行的 material 上下文。
+- findGlob: `string` 模板文件匹配正则。
+- target: `(globMatch: string) => string` 目标文件路径生成函数，参数为 `resourceKey。`
+- options?: `RenderTemplateDirOptions` glob 查找文件配置，具体函数可查看这里 [glob](https://www.npmjs.com/package/glob)。
+
+```ts
+type RenderTemplateDirOptions = {
+  nodir?: boolean;
+  dot?: boolean;
+  ignore?: string | readonly string[];
+};
+```

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          # 继续创建更多项目要素，比如应用入口
+```