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/topic-detail/changesets/release-note.mdx DELETED Viewed

@@ -1,259 +0,0 @@
----
-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/modern-js-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
-? 请选择你想创建的工程类型 模块
-? 请填写项目名称 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
-? 请选择你想创建的工程类型 模块
-? 请填写子项目名称 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/zh/guides/topic-detail/framework-plugin/extend.mdx DELETED Viewed

@@ -1,163 +0,0 @@
----
-title: 扩展插件 Hook
-sidebar_position: 5
----
-# 扩展插件 Hook
-本小节介绍如何通过动态注册 [Hook 模型](/guides/topic-detail/framework-plugin/hook) 的方式来扩展插件 Hook。
-## 示例
-这里我们用一个简单的例子演示一下。假设我们要添加一些管理控制台输出信息的 Hook。
-首先我们初始化一个空的项目文件，并添加基础依赖：
-```bash
-$ npx @modern-js/create modern-js-demo
-```
-### 创建 Hook
-我们先创建一个 Hook 模型：
-```ts title=config/plugin/myPlugin.ts
-import { createWaterfall } from '@modern-js/plugin';
-const message = createWaterfall<string[]>();
-```
-然后注册它：
-```ts title=config/plugin/myPlugin.ts
-import type { CliPlugin } from '@modern-js/core';
-export default (): CliPlugin => ({
-  name: 'my-plugin',
-  registerHook: {
-    message,
-  },
-});
-```
-添加 Hook 类型：
-```ts title=config/plugin/myPlugin.ts
-declare module '@modern-js/core' {
-  export interface Hooks {
-    message: typeof message;
-  }
-}
-```
-### 使用 Hook
-创建插件，通过 `commands` Hook 函数，添加命令处理逻辑：
-```ts title=config/plugin/myPlugin.ts
-import type { CliPlugin } from '@modern-js/core';
-export default (): CliPlugin => ({
-  name: 'my-plugin',
-  setup(api) {
-    return {
-      commands({ program }) {
-        program.command('message').action(async () => {
-          const hookRunners = api.useHookRunners();
-          const messages = hookRunners.message([]);
-          console.log(messages.join('\n'));
-        });
-      },
-    };
-  },
-});
-```
-最后 `config/plugin/myPlugin.ts` 的状态是：
-```ts title=config/plugin/myPlugin.ts
-import { createWaterfall } from '@modern-js/plugin';
-import type { CliPlugin } from '@modern-js/core';
-const message = createWaterfall<string[]>();
-export default (): CliPlugin => ({
-  name: 'my-plugin',
-  registerHook: {
-    message,
-  },
-  setup(api) {
-    return {
-      commands({ program }) {
-        program.command('message').action(async () => {
-          const hookRunners = api.useHookRunners();
-          const messages = hookRunners.message([]);
-          console.log(messages.join('\n'));
-        });
-      },
-    };
-  },
-});
-declare module '@modern-js/core' {
-  export interface Hooks {
-    message: typeof message;
-  }
-}
-```
-然后在 `modern.config.ts` 中添加这个插件：
-```ts title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
-import myPlugin from './config/plugin/myPlugin';
-export default defineConfig({
-  plugins: [myPlugin()],
-});
-```
-这时运行 `npx modern message` 就会执行相关逻辑，但由于没有收集到任何信息，所以控制台输出为空。
-那这里我们添加一个：
-```ts title=config/plugin/otherPlugin.ts
-import type { CliPlugin } from '@modern-js/core';
-export default (): CliPlugin => ({
-  name: 'other-plugin',
-  setup(api) {
-    return {
-      message(list) {
-        return [...list, '[foo] line 0', '[foo] line 1'];
-      },
-    };
-  },
-});
-```
-将它添加到配置中：
-```ts title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
-import myPlugin from './config/plugin/myPlugin';
-import otherPlugin from './config/plugin/otherPlugin';
-export default defineConfig({
-  plugins: [myPlugin(), otherPlugin()],
-});
-```
-这时运行 `npx modern message` 就可以在控制台看到信息了：
-```bash
-$ modern message
-[foo] line 0
-[foo] line 1
-```
-以上面这种方式就可以扩展出拥有各种能力的插件 Hook。

package/zh/guides/topic-detail/framework-plugin/hook.mdx DELETED Viewed

@@ -1,173 +0,0 @@
----
-title: Hook 模型
-sidebar_position: 2
----
-# Hook 模型
-首先介绍一下 Modern.js 的基础的插件系统中的一些内容，包括 Hook 模型的工作方式、各个 Hook 模型的运行模式、Manager 的工作模式。
-每种 Hook 模型都是独立的，可以独立管理运行函数。
-## 基础工作方式
-先以 Pipeline 为例，简单介绍一下 Hook 模型的工作方式。先看一个简单的例子：
-```ts
-import { createPipeline } from '@modern-js/plugin';
-// 1. 创建
-const pipeline = createPipeline<number, number>();
-// 2. 添加函数
-pipeline.use((count, next) => {
-  return next(count + 1);
-});
-pipeline.use((count, next) => {
-  return count * 2;
-});
-// 3. 执行
-pipeline.run(1); // 4
-pipeline.run(5); // 12
-```
-在这个例子中，创建了一个 `Pipeline<number, number>` 类型的 Pipeline（L3），这意味着运行它的时候，你需要传入一个 `number`，然后你会得到一个 `number`，而这个模型管理的函数的类型是：
-```ts
-(count: number, next: (nextCount: number) => number) => number;
-```
-这里全是 `number`，是因为我们创建的是 `Pipeline<number, number>` ，如果创建的是 `Pipeline<number, string>` 则运行它入参是 `number`，返回值是 `string`，对应管理的函数的类型会是：
-```ts
-(count: number, next: (nextCount: number) => string) => string;
-```
-创建好 Pipeline 之后，可以通过 `use` 添加函数（L5、L8），需要注意的是，添加的顺序就是他们默认的运行顺序，在这些函数中，你可以对 `count` 进行处理、返回一个值，如果你调用了 `next` 函数，则会运行后面的函数，即如果你添加了三个函数： `A`、`B`、`C`，如果你在 `A` 中调用 `next` 那么就会运行 `B`，同样的，如果你在 `B` 中调用 `next` 那么就会运行 `C`，而在上面的例子中，添加的第一个函数（L5）就运行了 `next`，所以这里就会运行第二个函数（L8），并且运行的返回值就是 第二个函数的返回值，如果在第一个函数中没有调用 `next`，直接返回，例如：
-```ts
-import { createPipeline } from '@modern-js/plugin';
-// 1. 创建
-const pipeline = createPipeline<number, number>();
-// 2. 添加函数
-pipeline.use((count, next) => {
-  return count + 1;
-});
-pipeline.use((count, next) => {
-  return count * 2;
-});
-// 3. 执行
-pipeline.run(1); // 2
-pipeline.run(5); // 6
-```
-则在运行 Pipeline 的时候就不会运行第二个函数，那么 Pipeline 的运行结果则就是第一个函数的返回值。
-最后，运行 Pipeline 的方式也显而易见就是调用 `pipeline.run` 。
-## 不同 Hook 模型的区别
-上面这部分就是 Pipeline 整体的一个工作模式的描述，其他的 Hook 模型的工作模式基本也是这样，主要的区别点，是函数类型、执行顺序，参数。
-### Pipeline
-上面的例子就是以 Pipeline 为例描述的，这里就不赘述了，在 Pipeline 这个大类中，提供了两个小类：Sync 和 Async，顾名思义，它们的区别就是管理的函数的类型是 Sync 的还是 Async 的。
-:::info
-当 Pipeline 中没有函数或者所有函数都调用了 `next` 函数，则就需要在运行的时候提供：
-```ts
-pipeline(
-  {},
-  {
-    onLast: () => {
-      // do something
-    },
-  },
-);
-```
-:::
-### Waterfall
-这种模型顾名思义，他的特点就是参数的顺序递交，即前面一个函数的返回值，将会成为下一个函数的入参，我们也用一个例子来看一下：
-```ts
-import { createWaterfall } from '@modern-js/plugin';
-// 1. 创建
-const waterfall = createWaterfall<number>();
-// 2. 添加函数
-waterfall.use(count => {
-  return count + 1;
-});
-waterfall.use(count => {
-  return count * 2;
-});
-// 3. 执行
-waterfall.run(1); // 4
-waterfall.run(5); // 12
-```
-这个例子中，创建了一个类型为 `Waterfall<number> `，即这个模型执行的入参和返回值是一样的，这个例子中都是 `number`，而它管理的函数的类型是：
-```ts
-(count: number) => number;
-```
-可能简单看这个例子感觉和上面的 Pipeline 功能一样，那需要注意的是，首先这里 Waterfall 管理的函数没有 next 函数作为第二个参数，所以它无法在函数内部通过调用 next 来先运行之后添加的函数，从而修改运行的顺序，其次这里的运行的入参的类型和返回值的类型必须是一样的（而 Pipeline 可以不一样）。
-同样的，在 Waterfall 这个大类中，也提供了 Sync 和 Async 的小类，分别对应 Sync 和 Async 的函数。
-### Workflow
-这种 Hook 模型与上面两种 Hook 模型的区别是，没有那么强的前后参数返回值递交的概念，在这个模型中，每个函数都是基于同样的入参，相对独立运行的，通过一个例子简单看一下：
-```ts
-import { createWorkflow } from '@modern-js/plugin';
-// 1. 创建
-const workflow = createWorkflow<number, number>();
-// 2. 添加函数
-workflow.use(count => {
-  return count + 1;
-});
-workflow.use(count => {
-  return count * 2;
-});
-// 3. 执行
-workflow.run(1); // [2, 2]
-workflow.run(5); // [6, 10]
-```
-在这个例子中，添加了两个函数，所以运行的结果就是这两个函数运行的结果形成的一个数组。
-虽然这种模型中没有那么强的前后参数返回值递交的概念，但依旧有执行顺序的区别，在 Workflow 这个大类中，提供了三个小类：Sync、Async、Parallel。他们之间的区别就是函数的执行顺序，当然默认的都是按照添加顺序执行，而在 Sync、Async 则是强制按照添加顺序执行，而 Parallel 则是 Async 模式的一个变体，即它使用的是 `Promise.all` 来执行所有函数，而 Async 则会 `await` 前面的函数运行结束。
-## Hook 模型对比
-<div style={{ width: "100%", overflowX: "scroll" }}>
-<div style={{ width: "150%" }}>
-|                  | 函数类型   | 执行顺序                                                   | 函数参数来源                                                                               | 执行返回值来源           | 倾向处理的任务类型                                                  | 函数 TS 类型                                           |
-| ---------------- | ---------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------ | ------------------------------------------------------------------- | ------------------------------------------------------ |
-| Pipeline         | Sync       | 默认执行第一个添加的函数，可以通过 next 调用之后添加的函数 | 第一个函数的参数来源是运行的参数，之后的函数的参数来源是，前一个函数向 next 函数传递的参数 | 第一个函数的返回值       | <ul><li>需要修改初始参数</li><li>需要修改函数执行顺序</li></ul>     | `(input: I, next: Next<I, O>) => O`                    |
-| AsyncPipeline    | Sync/Async | 默认执行第一个添加的函数，可以通过 next 调用之后添加的函数 | 第一个函数的参数来源是运行的参数，之后的函数的参数来源是，前一个函数向 next 函数传递的参数 | 第一个函数的返回值       | <ul><li>需要修改初始参数</li><li>需要修改函数执行顺序</li></ul>     | `(input: I, next: AsyncNext<I, O>) => O ｜ Promise<O>` |
-| WaterFall        | Sync       | 一直顺序执行                                               | 第一个函数的参数来源是运行的参数，之后的函数的参数来源是，前一个函数的返回值               | 最后一个函数的返回值     | <ul><li>需要修改初始参数</li><li>不需要修改函数执行顺序</li></ul>   | `(I: I) => I`                                          |
-| AsyncWaterFall   | Sync/Async | 一直顺序执行                                               | 第一个函数的参数来源是运行的参数，之后的函数的参数来源是，前一个函数的返回值               | 最后一个函数的返回值     | <ul><li>需要修改初始参数</li><li>不需要修改函数执行顺序</li></ul>   | `(I: I) => I ｜ Promise<I>`                            |
-| Workflow         | Sync       | 一直顺序执行                                               | 所有函数的入参都是运行的参数                                                               | 所有函数返回值形成的数组 | <ul><li>不需要修改初始参数</li><li>不需要修改函数执行顺序</li></ul> | `(I: I) => O`                                          |
-| AsyncWorkflow    | Sync/Async | 一直顺序执行                                               | 所有函数的入参都是运行的参数                                                               | 所有函数返回值形成的数组 | <ul><li>不需要修改初始参数</li><li>不需要修改函数执行顺序</li></ul> | `(I: I) => O ｜ Promise<O>`                            |
-| ParallelWorkFlow | Sync/Async | 异步执行                                                   | 所有函数的入参都是运行的参数                                                               | 所有函数返回值形成的数组 | <ul><li>不需要修改初始参数</li><li>不关心执行顺序</li></ul>         | `(I: I) => O ｜ Promise<O>`                            |
-</div>
-</div>
-Workflow、Waterfall 其实都是 Pipeline 的变体，Pipeline 可以通过特定的写法来实现 Workflow、Waterfall，但都较为麻烦，有许多隐形的约定。为了方便使用，提供了这两种变体来满足这种特殊场景。