@modern-js/main-doc 2.21.1 → 2.22.1

package/docs/zh/guides/topic-detail/generator/create/option.md

@@ -0,0 +1,151 @@
+---
+sidebar_position: 2
+---
+
+# CLI 参数
+
+`@modern-js/create` 提供了很多配置参数用于配置其执行过程中的行为，可以通过 `--help` 参数进行查看：
+
+```bash
+npx @modern-js/create@latest --help
+
+Usage: npx @modern-js/create@latest [projectDir]
+
+创建 Modern.js 工程方案
+
+Options:
+  --version                当前 create 工具版本号
+  --lang <lang>            设置 create 工具语言(zh 或者 en)
+  -c, --config <config>    创建项目默认配置(JSON 字符串) (default: "{}")
+  -d,--debug               开启 Debug 模式，打印调试日志信息 (default: false)
+  --mwa                    一键创建 Web 应用(使用默认配置) (default: false)
+  --module                 一键创建 Module 应用(使用默认配置) (default: false)
+  --monorepo               一键创建 Monorepo 应用(使用默认配置) (default: false)
+  --generator <generator>  使用自定义生成器
+  -p, --plugin <plugin>    使用生成器插件创建新的工程方案类型或定制化 Modern.js 工程方案 (default: [])
+  --dist-tag <distTag>     生成项目时生成器使用特殊的 npm Tag (default: "")
+  --packages <packages>    创建项目指定特定依赖版本信息 (default: "{}")
+  --registry <registry>    在创建过程中定制 npm Registry (default: "")
+  --no-need-install        无需安装依赖
+  -h, --help               display help for command
+
+Commands:
+  clean-cache              清除本地生成器缓存
+```
+
+下面将针对这些参数做详细介绍：
+
+## [projectDir]
+
+项目目录名称。
+
+执行 `@modern-js/create` 时，默认会在当前目录创建 `projectDir` 文件夹，并在该文件夹下初始化项目。该参数为空时，将会在当前目录直接生成初始化项目。
+
+:::info
+如果 `projectDir` 所在目录内容不为空，将会提示是否继续创建，推荐在空目录下进行项目初始化操作。
+:::
+
+## --version
+
+获取 `@modern-js/create` 工具版本。
+
+```bash
+npx @modern-js/create@latest --version
+
+[INFO] @modern-js/create v2.21.1
+```
+
+## --lang \<lang>
+
+执行执行语言，支持 `zh` 和 `en`。
+
+默认情况下，`@modern-js/create` 会自动识别用户的系统语言，选择使用中文或者英文，如果识别失败或者不符合使用习惯，可以使用该参数手动指定。
+
+## -c, --config \<config>
+
+指定项目默认配置。
+
+默认情况下，`@modern-js/create` 在执行过程中会出现选择语言、包管理工具等交互问题，当需要提前指定这些配置内容时，可以通过该字段传入。
+
+该字段为 JSON 字符串，例如需指定包管理工具时：
+
+```bash
+npx @modern-js/create@latest --config '{"packageManager": "pnpm"}'
+```
+
+`config` 支持的参数可查看[配置参数](/guides/topic-detail/generator/create/config.html)。
+
+## -d,--debug
+
+展示调试日志。
+
+当在使用过程中遇到问题时，可以使用该参数显示调试日志，方便快速定位问题位置及对问题进行排查。
+
+## --mwa
+
+快速创建 Web 应用项目。
+
+## --module
+
+快速创建 Npm 模块项目。
+
+## --monorepo
+
+快速创建 Monorepo 项目。
+
+## -p, --plugin \<plugin>
+
+指定生成器插件。
+
+`@modern-js/create` 支持使用生成器插件定制 Modern.js 默认的工程方案类型或者添加工程方案类型场景，详情可查看[开发生成器插件](/guides/topic-detail/generator/plugin/structure.html)。
+
+## --generator \<generator>
+
+指定微生成器。
+
+<!-- TODO 详情可查看[开发微生成器]-->
+`@modern-js/create` 支持使用微生成器完全定制项目生成流程。
+
+## --dist-tag \<distTag>
+
+指定生成器及 Modern.js 相关依赖版本。
+
+`@modern-js/create` 执行过程中会执行更小的微生成器，默认会使用 `latest` 的微生成器版本，使用该参数可以指定执行的微生成器的版本号和对应的安装 Modern.js 相关依赖的版本。
+
+比如使用 `next` 版本：
+
+```bash
+npx @modern-js/create@next --dist-tag next
+```
+
+## --packages \<packages>
+
+创建项目是指定特定包版本依赖。
+
+在创建项目时如果有需要指定特定包版本，可以使用该参数。该参数会在项目根目录的 `package.json` 中配置 `pnpm.overrides`(包管理工具选择 pnpm) 或者 `resolutions` 锁定包版本号。
+
+该参数值为 JSON 字符串。
+
+例如指定 react 版本：
+
+```bash
+npx @modern-js/create@latest --packages '{"react":"^17"}'
+```
+
+## --registry \<registry>
+
+指定执行子生成器和获取项目依赖版本的 npm registry。
+
+## --no-need-install
+
+忽略自动安装依赖。
+
+默认情况下，`@modern-js/create` 在创建项目完成后会自动安装依赖，使用该参数可以忽略安装依赖步骤。
+
+## clean-cache
+
+`@modern-js/create` 默认会在执行机器的 tmp 目录生成子生成器缓存用于加快生成器执行速度，在需要刷新缓存或者缓存出现问题时可以使用该命令删除缓存。
+
+```bash
+npx @modern-js/create@latest clean-cache
+```

package/docs/zh/guides/topic-detail/generator/create/use.mdx

@@ -0,0 +1,66 @@
+---
+sidebar_position: 1
+---
+
+# 使用
+
+Modern.js 提供了 `@modern-js/create` 工具用于创建 Modern.js 提供的工程方案项目，例如 [Web 应用](https://modernjs.dev/)、[Npm 模块](https://modernjs.dev/module-tools)、[文档站](https://modernjs.dev/doc-tools)、[Monorepo](/guides/topic-detail/monorepo/intro.html) 等。
+
+下面将介绍 `@modern-js/create` 的使用姿势。
+
+## 环境准备
+
+import Prerequisites from "@site-docs/components/prerequisites"
+
+<Prerequisites />
+
+## 使用 `@modern-js/create` 创建项目
+
+不需要全局安装 `@modern-js/create`，直接使用 npx 执行即可：
+
+```bash
+npx @modern-js/create@latest [projectDir]
+```
+
+:::info
+`[projectDir]` 为项目目录名称，不填写将会在当前目录创建项目。
+:::
+
+执行过程中需要根据提示完成交互，创建符合需求的项目。
+
+### 创建 Web 应用项目
+
+```bash
+npx @modern-js/create@latest web-app
+? 请选择你想创建的工程类型 Web 应用
+? 请选择开发语言 TS
+? 请选择包管理工具 pnpm
+? 请选择构建工具 webpack
+```
+
+### 创建 Npm 模块项目
+
+```bash
+npx @modern-js/create@latest npm-module
+? 请选择你想创建的工程类型 Npm 模块
+? 请填写项目名称 npm-module
+? 请选择开发语言 TS
+? 请选择包管理工具 pnpm
+```
+
+### 创建文档站项目
+
+```bash
+npx @modern-js/create@latest doc-website
+? 请选择你想创建的工程类型 文档站
+? 请选择包管理工具 pnpm
+```
+
+### 创建 Monorepo
+
+```bash
+npx @modern-js/create@latest monorepo
+? 请选择你想创建的工程类型 Monorepo
+? 请选择包管理工具 pnpm
+```
+

package/docs/zh/guides/topic-detail/generator/new/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "new 命令",
+  "position": 2
+}

package/docs/zh/guides/topic-detail/generator/new/config.md

@@ -0,0 +1,153 @@
+---
+sidebar_position: 3
+---
+
+# 配置参数
+
+`new` 命令提供了 [--config](/guides/topic-detail/generator/new/option.html#-c,---config-<config>) 参数，用于提前指定执行过程中交互问题的答案。
+
+这里将介绍不同情况下，可以在 `config` 中配置的字段及字段值。
+
+## 通用配置
+
+### actionType
+
+问题：请选择你想要的操作
+
+选项：
+
+- 创建工程元素 -- element
+
+- 启用可选功能 -- function
+
+- 自动重构 -- refactor
+
+## Web 应用
+
+### element
+
+问题：请选择创建元素类型
+
+选项：
+
+- 新建「应用入口」 -- entry
+
+- 新建「自定义 Web Server」源码目录 -- server
+
+### name
+
+问题： 请填写入口名称
+
+:::info
+新建应用入口时需要该配置，该配置值为字符串类型。
+:::
+
+### function
+
+问题：请选择功能名称
+
+选项：
+
+- 启用「Rspack 构建」 -- rspack
+
+- 启用 「Tailwind CSS」 支持 -- tailwindcss
+
+- 启用「BFF」功能 -- bff
+
+- 启用「SSG」功能 -- ssg
+
+- 启用「SWC 编译」-- swc
+
+- 启用「微前端」模式 -- micro_frontend
+
+- 启用「单元测试 / 集成测试」功能 -- test
+
+- 启用「基于 UA 的 Polyfill」功能 -- polyfill
+
+- 启用「全局代理」 -- proxy
+
+- 启用「Visual Testing (Storybook)」模式 -- mwa_storybook
+
+### bffType
+
+问题：请选择 BFF 类型
+
+选项：
+
+- 函数模式 -- func
+
+- 框架模式 -- framework
+
+:::info
+启用 BFF 功能时需要该配置。
+:::
+
+### framework
+
+问题：请选择运行时框架
+
+选项：
+
+- Express -- express
+
+- Koa -- koa
+
+:::info
+启用 BFF 功能时需要该配置。
+:::
+
+### refactor
+
+问题：请选择重构类型
+
+选项：
+
+- 使用 React Router v5 -- react_router_5
+
+## Npm 模块
+
+### function
+
+问题：启用可选功能
+
+选项：
+
+- 启用「单元测试 / 集成测试」功能 -- test
+
+- 启用 「Tailwind CSS」 支持 -- tailwindcss
+
+- 启用「Storybook」 -- storybook
+
+- 启用「Runtime API」 -- runtime_api
+
+## Monorepo
+
+### sub_solution
+
+问题：请选择你想创建的工程类型
+
+选项：
+
+- Web 应用 -- mwa
+
+- Web 应用（测试）-- mwa_test
+
+- Npm 模块 -- module
+
+- Npm 模块（内部）-- inner_module
+
+### packageName
+
+问题：请填写子项目名称
+
+:::info
+子项目的 `package.json` 的 name 字段值，该配置值为字符串类型。
+:::
+
+### packagePath
+
+问题：请填写子项目目录名称
+
+:::info
+子项目基于 apps 或者 packages 目录的子目录名称，该字段为字符串类型。
+:::

package/docs/zh/guides/topic-detail/generator/new/option.md

@@ -0,0 +1,67 @@
+---
+sidebar_position: 2
+---
+
+# CLI 参数
+
+`new` 命令提供了很多配置参数用于配置其执行过程中的行为，可以通过 `--help` 参数进行查看：
+
+```bash
+npm run new --help
+
+Usage: modern new [options]
+
+启用可选功能
+
+Options:
+  --lang <lang>          设置 new 命令执行语言(zh 或者 en)
+  -c, --config <config>  生成器运行默认配置(JSON 字符串)
+  -d, --debug            开启 Debug 模式，打印调试日志信息 (default: false)
+  --dist-tag <tag>       生成器使用特殊的 npm Tag 版本
+  --registry <registry>  生成器运行过程中定制 npm Registry
+  -h, --help             display help for command
+```
+
+下面将针对这些参数做详细介绍：
+
+## --lang \<lang>
+
+执行执行语言，支持 `zh` 和 `en`。
+
+默认情况下，`new` 命令会自动识别用户的系统语言，选择使用中文或者英文，如果识别失败或者不符合使用习惯，可以使用该参数手动指定。
+
+## -c, --config \<config>
+
+指定项目默认配置。
+
+默认情况下，new 命令在执行过程中会出现选择操作类型、开启功能等交互问题，当需要提前指定这些配置内容时，可以通过该字段传入。
+
+该字段为 JSON 字符串，例如需指定 BFF 框架时：
+
+```bash
+npm run new --config '{"framework": "express"}'
+```
+
+`config` 支持的参数可查看[配置参数](/guides/topic-detail/generator/new/config.html)。
+
+## -d,--debug
+
+展示调试日志。
+
+当在使用过程中遇到问题时，可以使用该参数显示调试日志，方便快速定位问题位置及对问题进行排查。
+
+## --registry \<registry>
+
+指定执行子生成器和获取项目依赖版本的 npm registry。
+
+## --dist-tag \<distTag>
+
+指定生成器版本。
+
+`new` 命令执行过程中会执行更小的微生成器，默认会使用 `latest` 的微生成器版本，使用该参数可以指定执行的微生成器的版本号的版本。
+
+比如使用 `next` 版本：
+
+```bash
+npm run new --dist-tag next
+```

package/docs/zh/guides/topic-detail/generator/new/use.md

@@ -0,0 +1,94 @@
+---
+sidebar_position: 1
+---
+
+# 使用
+
+在 Web 应用、 Npm 模块和 Monorepo 项目中，我们提供了 `new` 命令用于创建项目元素、开启功能和创建子项目。
+
+## Web 应用
+
+Web 应用项目通过 `@modern-js/app-tools` 提供 `new` 命令。
+
+new 命令提供了三种操作类型：
+
+- 创建工程元素
+
+- 启用可选功能
+
+- 自动重构
+
+每种操作类型都提供了对应支持的列表，可根据项目情况进行选择。
+
+例如：
+
+创建新的应用入口：
+
+```bash
+npm run new
+? 请选择你想要的操作 创建工程元素
+? 请选择创建元素类型 新建「应用入口」
+? 请填写入口名称 entry
+```
+
+执行完成后将会在项目 `src` 目录创建新入口对应名称的文件夹及默认入口文件，并且自动帮忙整理之前 `src` 下入口文件到 `package.json` 中 `name` 字段对应的文件夹中。
+
+开启 BFF 功能：
+
+```bash
+npm run new
+? 请选择你想要的操作 启用可选功能
+? 请选择功能名称 启用「BFF」功能
+? 请选择 BFF 类型 函数模式
+? 请选择运行时框架 Express
+```
+
+执行完成后将会在项目安装 BFF 相关依赖，并创建 api 目录用于 BFF 模块的开发并提供提示信息用于注册 BFF 插件。
+
+:::info
+这里未帮助用户自动注册插件，原因是由于 `modern.config.[tj]s` 在项目生命周期中变化比较复杂，可能存在模块之间互相引用问题，让用户手动注册能保证修改配置的正确性。
+
+在后续定制化的开发中，如果有类似的需求，也可以通过提示的方式给到使用方操作指南，让用户对文件进行手动操作。
+:::
+
+:::warning
+执行 new 命令时可能会出现需要开启的功能不在列表中，需要检查一下项目 `package.json` 中是否已经安装对应功能的插件，如果仍需使用 new 命令开启，需要先手动移除对应的插件依赖。
+:::
+
+## Npm 模块
+
+Npm 模块项目通过 `@modern-js/module-tools` 提供 new 命令。
+
+new 命令提供了启用可选功能的能力。
+
+例如：
+
+开启 Storybook 能力：
+
+```bash
+npm run new
+? 请选择你想要的操作 启用可选功能
+? 请选择功能名称 启用「Storybook」
+```
+
+执行完成后将会在项目安装 Storybook 插件相关依赖，增加 `storybook` 命令，创建 `stories` 目录用于 Storybook 模块的开发并提供提示信息用于注册 Storybook 插件。
+
+## Monorepo
+
+Monorepo 项目通过 `@modern-js/monorepo-tools` 提供 new 命令。
+
+new 命令提供了创建子项目的能力。
+
+例如：
+
+创建 Web 应用子项目：
+
+```bash
+? 请选择你想创建的工程类型 Web 应用
+? 请填写子项目名称 web_app
+? 请填写子项目目录名称 web_app
+? 请选择开发语言 TS
+? 请选择构建工具 webpack
+```
+
+执行完成后将会在项目 apps 目录创建 `web_app` 的子项目，在子项目目录中依然可以执行 new 命令创建项目元素和开启功能。

package/docs/zh/guides/topic-detail/generator/plugin/_category_.json

@@ -1,4 +1,4 @@
 {
-  "label": "开发生成器插件",
-  "position": 4
+  "label": "生成器插件",
+  "position": 2
 }

package/docs/zh/guides/topic-detail/generator/plugin/api/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "API",
-  "position": 4
+  "position": 5
 }

package/docs/zh/guides/topic-detail/generator/plugin/api/afterForged.md

@@ -0,0 +1,50 @@
+---
+sidebar_position: 3
+---
+
+# afterForged
+
+`afterForged` 为生成器插件中用于文件操作后其他步骤操作的生命周期函数。
+
+## 类型
+
+```ts
+export type AfterForgedAPI = {
+  isInGitRepo: () => Promise<boolean>;
+  initGitRepo: () => Promise<void>;
+  gitAddAndCommit: (commitMessage: string) => Promise<void>;
+  install: () => Promise<void>;
+};
+
+export type PluginAfterForgedFunc = (api: AfterForgedAPI, inputData: Record<string, unknown>) => Promise<void>;
+
+export interface IPluginContext {
+   afterForged: (func: PluginAfterForgedFunc) => void;
+  ...
+}
+```
+
+## API
+
+下面将分别介绍 api 参数提供的 API。
+
+### isInGitRepo
+
+判断当前项目是否为一个 Git 仓库。
+
+### initGitRepo
+
+初始化当前项目为 Git 仓库。
+
+### gitAddAndCommit
+
+提交当前仓库变更。
+
+参数：
+
+- `commitMessage`: commit 信息。
+
+
+### install
+
+在项目根目录安装依赖。`install` 函数中将根据 `packageManager` 的值使用对应的包管理工具安装依赖。