npm - @modern-js/main-doc - Versions diffs - 2.8.0 → 2.10.0 - Mend

@modern-js/main-doc 2.8.0 → 2.10.0

Files changed (1096) 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/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
-? 请选择你想创建的工程类型 模块
-? 请填写项目名称 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/plugin-api.mdx DELETED Viewed

@@ -1,117 +0,0 @@
----
-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/zh/guides/topic-detail/generator/codesmith/api/fs.mdx DELETED Viewed

@@ -1,54 +0,0 @@
----
-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 handlebarApi = new HandlebarsAPI(generator);
-  await handlebarsAPI.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/zh/guides/topic-detail/generator/plugin/develop.mdx DELETED Viewed

@@ -1,125 +0,0 @@
----
-sidebar_position: 3
----
-# 如何开发生成器插件
-## 创建项目
-Modern.js 提供了生成器插件用于创建开发项目，可直接执行以下命令创建:
-```bash
-npx @modern-js/create plugin --plugin @modern-js/generator-plugin-plugin
-```
-插件类型不同，会提问不同的问题，可根据需求选择插件类型
-### 扩展工程方案
-```
-? 请选择你想创建的工程类型 模块
-? 请选择项目场景 生成器插件
-? 插件包名 plugin
-? 请选择开发语言 TS
-? 请选择包管理工具 pnpm
-? 插件类型 扩展
-? 插件基础类型 应用
-```
-### 创建工程方案场景
-```
-? 请选择你想创建的工程类型 模块
-? 请选择项目场景 生成器插件
-? 插件包名 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/zh/guides/topic-detail/monorepo/create-sub-project.mdx DELETED Viewed

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