@modern-js/main-doc 2.21.1 → 2.22.0

package/docs/zh/guides/basic-features/routes.mdx

@@ -449,7 +449,7 @@ export const init = (context: RuntimeContext) => {
 在约定式路由下， Modern.js 会根据路由，自动地对路由进行分片，当用户访问具体的路由时，会自动加载对应的分片，这样可以有效地减少首屏加载的时间。但这也带来了一个问题，当用户访问一个路由时，如果该路由对应的分片还未加载完成，就会出现白屏的情况。
 这种情况下你可以通过定义 `Loading` 组件，在静态资源加载完成前，展示一个自定义的 `Loading` 组件。
 
-为了进一步提升用户体验，减少 loading 的时间，Modern.js 支持在 Link 组件上定义 `prefetch` 属性，可以提前对静态资源和数据进行加载， `prefetch` 属性有三个可选值：
+为了进一步提升用户体验，减少 loading 的时间，Modern.js 支持在 Link 组件上定义 `prefetch` 属性，可以提前对静态资源和数据进行加载：
 
 ```tsx
 <Link prefetch="intent" to="page">
@@ -461,6 +461,8 @@ export const init = (context: RuntimeContext) => {
 
 :::
 
+`prefetch` 属性有三个可选值：
+
 - `none`， 默认值，不会做 prefetch，没有任何额外的行为。
 - `intent`，这是我们推荐大多数场景下使用的值，当你把鼠标放在 Link 上时，会自动开始加载对应的分片和 Data Loader 中定义的数据，当鼠标移开时，会自动取消加载。在我们的测试中，即使是快速点击，也能减少大约 200ms 的加载时间。
 - `render`，当 Link 组件渲染时，就会加载对应的分片和 Data Loader 中定义的数据。
@@ -505,8 +507,6 @@ export default () => {
 Modern.js 默认对约定式路由做了一系列资源加载及渲染上的优化，并且提供了开箱即用的 SSR 能力，而这些能力，在使用自控路由时，都需要开发者自行封装，推荐开发者使用约定式路由。
 :::
 
-使用自控式路由时，如果开发者关闭了 [`runtime.router`](/configure/app/runtime/router) 配置，并直接使用 `react-router-dom`，那还需要根据 React Router 文档自行包裹 `Provider`。
-
 ## 其他路由方案
 
 默认情况下，Modern.js 会开启内置的路由方案，即 React Router。
@@ -519,7 +519,9 @@ export default defineConfig({
 });
 ```
 
-Modern.js 从 `@modern-js/runtime/router` 命名空间暴露了 React Router 的 API 供开发者使用，保证开发者和 Modern.js 中使用同一份代码。另外，这种情况下，React Router 的代码会被打包到 JS 产物中。如果项目已经有自己的路由方案，或者不需要使用客户端路由，可以关闭这个功能。
+如上述配置，当开启 [`runtime.router`](/configure/app/runtime/router) 配置时，Modern.js 会从 `@modern-js/runtime/router` 命名空间导出 React Router 的 API 供开发者使用，保证开发者和 Modern.js 中使用同一份代码，并自动根据 router 配置包裹 `Provider` 组件。另外，这种情况下，React Router 的代码会被打包到 JS 产物中。
+
+如果项目已经有自己的路由方案，或者不需要使用客户端路由，可以关闭这个功能。
 
 ```js
 export default defineConfig({
@@ -529,5 +531,6 @@ export default defineConfig({
 });
 ```
 
+如上述配置， 如果关闭了 [`runtime.router`](/configure/app/runtime/router) 配置，并直接使用 `react-router-dom` 进行项目路由管理时，还需要根据 React Router 文档自行包裹 `Provider`。
 
 

package/docs/zh/guides/concept/entries.mdx

@@ -33,9 +33,9 @@ Modern.js 初始化的项目是单入口的（SPA），项目结构如下：
 在 Modern.js 项目中，你可以很方便的将单入口切换成多入口，直接在项目下执行 `pnpm run new`，通过生成器创建入口即可：
 
 ```bash
-? 请选择你想要的操作：创建工程元素
-? 创建工程元素：新建「应用入口」
-? 请填写入口名称：new-entry
+? 请选择你想要的操作 创建工程元素
+? 请选择创建元素类型 新建「应用入口」
+? 请填写入口名称 new-entry
 ```
 
 执行后，Modern.js 会自动生成一个新的入口目录，此时可以看到 `src/` 目录变成如下结构：

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

@@ -0,0 +1,4 @@
+{
+  "label": "@modern-js/create",
+  "position": 1
+}

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

@@ -0,0 +1,76 @@
+---
+sidebar_position: 3
+---
+
+# 配置参数
+
+`@modern-js/create` 提供了 [--config](/guides/topic-detail/generator/create/option.html#-c,---config-<config>) 参数，用于提前指定执行过程中交互问题的答案。
+
+这里将介绍不同情况下，可以在 `config` 中配置的字段及字段值。
+
+
+## 通用配置
+
+### solution
+
+问题：请选择你想创建的工程类型
+
+选项：
+
+- Web 应用 -- mwa
+
+- Npm 模块 -- module
+
+- 文档站 -- doc
+
+- Monorepo -- monorepo
+
+### scenes
+
+问题：请选择项目场景
+
+选项：
+
+使用自定义生成器插件时的插件关键字列表。
+
+## Web 应用
+
+import LanguageConfig from '@site-docs/components/language-config';
+
+<LanguageConfig />
+
+import PackageManager from '@site-docs/components/package-manager';
+
+<PackageManager />
+
+### buildTools
+
+问题：请选择构建工具
+
+选项：
+
+- webpack -- webpack
+
+- Rspack -- rspack
+
+## Npm 模块
+
+### packageName
+
+问题：请填写项目名称
+
+:::info
+Npm 模块的 `package.json` 的 name 字段值，该配置值为字符串类型。
+:::
+
+<LanguageConfig />
+
+<PackageManager />
+
+## 文档站
+
+<PackageManager />
+
+## Monorepo
+
+<PackageManager />

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
 }