@modern-js/main-doc 2.0.0-beta.0 → 2.0.0-beta.1

package/zh/guides/topic-detail/{generator-plugin → generator/plugin}/develop.md

@@ -52,13 +52,13 @@ npx @modern-js/create plugin --plugin @modern-js/generator-plugin-plugin
 
 插件默认导出一个函数，函数参数为 `context`，`context` 上提供一些方法可直接对当前项目进行操作。
 
-简单介绍一下提供的方法，完整的 API 列表可查看[生成器插件API](/docs/apis/generator/plugin/introduce)。
+简单介绍一下提供的方法，完整的 API 列表可查看[生成器插件API](/docs/guides/topic-detail/generator/plugin/api/introduce)。
 
 ### 自定义输入
 
 - addInputBefore
 
-在默认的输入前添加输入，比如在`选择包管理工具`问题前添加问题，具体 Modern.js 每个问题的配置可查看[生成器配置](/docs/configure/generator/introduce)。
+在默认的输入前添加输入，比如在`选择包管理工具`问题前添加问题，具体 Modern.js 每个问题的配置可查看[工程方案配置](/docs/guides/topic-detail/generator/config/common)。
 
 ```ts
 context.addInputBefore('packageManager', {
@@ -89,7 +89,7 @@ context.setInput('test', 'options', [{ key: 'option1', name: '选项一' }])
 
 当需要新的模板文件时，可直接在 `templates` 目录添加，在 `onForged` 函数中可直接对 `templates` 目录文件进行操作，比如下方的 `addFile` 中 `templateFile` 参数就为 `templates` 目录下的文件。这里不需要显示的声明 `templates`，直接写相对于 `templates` 的相对路径即可。
 
-`onForged` 中支持的 API 函数也可参考 [生成器插件API](/docs/apis/generator/plugin/hook/onForged)。
+`onForged` 中支持的 API 函数也可参考 [生成器插件API](/docs/guides/topic-detail/generator/plugin/api/hook/onForged)。
 
 ```ts
 context.onForged(async (api: ForgedAPI, input: Record<string, unknown>) => {
@@ -117,4 +117,4 @@ context.onForged(async (api: ForgedAPI, input: Record<string, unknown>) => {
 
 `input` 为当前用户输入，可用于获取用户当前的输入信息及配置信息。
 
-`afterForged` 中支持的 API 函数也可参考 [生成器插件API](/docs/apis/generator/plugin/hook/afterForged)。
+`afterForged` 中支持的 API 函数也可参考 [生成器插件API](/docs/guides/topic-detail/generator/plugin/api/hook/afterForged)。

package/zh/guides/topic-detail/generator/project.md

@@ -0,0 +1,117 @@
+---
+sidebar_position: 2
+---
+
+# 项目生成器
+
+Modern.js 提供了 `@modern-js/create` 作为项目生成器用于进行 Modern.js 工程方案项目创建。
+
+## 使用
+
+不需要全局安装 `@modern-js/create`，直接使用 npx 执行该工具即可：
+
+```bash
+npx @modern-js/create [projectDir]
+```
+
+:::info
+使用 npx 可以每次获取最新版本的 `@modern-js/create`。
+:::
+
+## 参数
+
+### [projectDir]
+
+项目目录名称。
+
+执行上述命令时，默认会在当前目录创建 `projectDir` 文件夹，并在该文件夹下初始化项目。该参数为空时，将会在当前目录直接生成初始化项目。
+
+### --version
+
+获取 `@modern-js/create` 工具版本。
+
+```bash
+$ npx @modern-js/create --version
+
+[INFO] @modern-js/create v2.0.0
+```
+
+### --lang
+
+指定执行语言，支持 `zh` 和 `en`。
+
+默认情况下，`@modern-js/create` 会自动识别用户的系统语言，选择使用中文或者英文，如果识别失败或者想手动指定语言，可以使用该参数。
+
+### -c, --config
+
+指定项目默认配置。
+
+默认情况下，`@modern-js/create` 在执行过程中会出现选择语言、包管理工具等交互问题，当需要提前指定这些配置内容时，可以通过该字段传入。
+
+该字段为 JSON 字符串，例如需执行包管理工具时：
+
+```bash
+npx @modern-js/create --config '{"packageManager": "pnpm"}'
+```
+
+具体配置信息可查看[工程方案配置](/docs/guides/topic-detail/generator/config/common)。
+
+###  --no-need-install
+
+默认情况下，`@modern-js/create` 在创建项目完成后会自动安装依赖，使用该参数可以忽略安装依赖步骤。
+
+### --dist-tag <distTag\>
+
+指定生成器及 Modern.js 相关依赖版本。
+
+`@modern-js/create` 执行过程中会执行更小的微生成器，使用该参数可以执行执行的微生成器的版本号和对应的安装 Modern.js 相关依赖的版本号。
+
+### --registry <registry/>
+
+执行获取生成器及 npm 包的 npm registry。
+
+### --debug
+
+显示生成器执行过程中的调试日志信息。
+
+### --mwa
+
+一键创建应用工程方案项目。
+
+使用该参数后，`@modern-js/create` 将会使用配置默认值创建应用项目。
+
+### --module
+
+一键创建模块工程方案项目。
+
+使用该参数后，`@modern-js/create` 将会使用配置默认值创建模块项目。
+
+### --monorepo
+
+一键创建 Monorepo 工程方案项目。
+
+使用该参数后，`@modern-js/create` 将会使用配置默认值创建 Monorepo 项目。
+
+### --plugin <plugin\>
+
+指定生成器插件。
+
+Modern.js 支持使用生成器插件定制 Modern.js 默认的工程方案类型或者添加工程方案类型场景，该参数用户指定定制的生成器插件。
+
+关于定制生成器插件可以参考[开发生成器插件](/docs/guides/topic-detail/generator/plugin/abstract)。
+
+### --generator <generator\>
+
+指定微生成器。
+
+默认情况下 `@modern-js/create` 会执行 Modern.js 框架内置的微生成器，如果你需要执行定制的微生成器，又需要使用 `npx @modern-js/create` 的姿势，可直接使用该参数。
+
+关于定制微生成器可以参考[开发微生成器](/docs/guides/topic-detail/generator/codesmith/introduce)。
+
+### --packages <packages\>
+
+创建项目是指定特定包版本依赖。
+
+在创建项目时如果有需要指定特定包版本，可以使用该参数。该参数会在项目根目录的 `package.json` 中配置 `pnpm.overrides`(包管理工具选择 pnpm) 或者 `resolutions` 锁定包版本号。
+
+该参数值为 JSON 字符串。

package/zh/guides/topic-detail/micro-frontend/debugging.md

@@ -16,7 +16,7 @@ title: 子应用调试
 
 #### 配置
 
-```js title="modern.config.js"
+```typescript title="modern.config.ts"
 export default defineConfig({
   runtime: {
     router: true,
@@ -38,7 +38,7 @@ export default defineConfig({
 
 #### 加载子应用
 
-使用 [useModuleApps](/docs/apis/app/runtime/app/use-module-apps) API 获取子应用组件，并加载子应用。
+使用 [useModuleApps](/docs/apis/app/runtime/core/use-module-apps) API 获取子应用组件，并加载子应用。
 
 ```tsx title=App.tsx
 import { useModuleApps } from '@modern-js/plugin-garfish';
@@ -61,7 +61,7 @@ function App() {
 
 #### 配置
 
-```js title="modern.config.js"
+```typescript title="modern.config.ts"
 export default defineConfig({
   deploy: {
     microFrontend: true,
@@ -99,7 +99,7 @@ function App() {
 
 #### 配置
 
-```js title="modern.config.js"
+```typescript title="modern.config.ts"
 export default defineConfig({
   server: {
     enableMicroFrontendDebug: true,
@@ -128,7 +128,7 @@ export default defineConfig({
 
 #### 配置
 
-```js title="modern.config.js"
+```typescript title="modern.config.ts"
 export default defineConfig({
   deploy: {
     microFrontend: true,

package/zh/guides/topic-detail/micro-frontend/route-mode.md

@@ -14,7 +14,7 @@ title: 加载子应用
 
 假设我们的子应用列表配置如下：
 
-```js title="modern.config.js"
+```typescript title="modern.config.ts"
 export default defineConfig({
   runtime: {
     masterApp: {
@@ -63,7 +63,7 @@ function App() {
 
 **集中式路由** 是将子应用的激活路由集中配置的方式。我们给子应用列表信息添加 `activeWhen` 字段来启用 **集中式路由**。
 
-```js title="modern.config.js"Å {8,13}
+```typescript title="modern.config.ts"Å {8,13}
 export default defineConfig({
   runtime: {
     masterApp: {

package/zh/guides/troubleshooting/compile.md

@@ -99,7 +99,7 @@ rm -rf ./node_modules/.cache
 
 如果需要将 JS、CSS 等静态资源上传到 CDN 使用，那么可以通过 [output.assetPrefix](/docs/configure/app/output/asset-prefix) 配置来设置静态资源的 URL 前缀。
 
-```js title="modern.config.js"
+```typescript title="modern.config.ts"
 import { defineConfig } from '@modern-js/app-tools';
 
 export default defineConfig({
@@ -117,7 +117,7 @@ export default defineConfig({
 
 注册该插件的示例代码如下，更详细的用法请参考 [eslint-webpack-plugin](https://github.com/webpack-contrib/eslint-webpack-plugin) 文档。
 
-```js title="modern.config.js"
+```typescript title="modern.config.ts"
 import { defineConfig } from '@modern-js/app-tools';
 import ESLintPlugin from 'eslint-webpack-plugin';
 
@@ -142,7 +142,7 @@ export default defineConfig({
 
 配置 [webpack-subresource-integrity](https://github.com/waysact/webpack-subresource-integrity) 的示例如下：
 
-```js title="modern.config.js"
+```typescript title="modern.config.ts"
 import { defineConfig } from '@modern-js/app-tools';
 import { SubresourceIntegrityPlugin } from 'webpack-subresource-integrity';
 

package/zh/tutorials/first-app/c01-getting-started/1.4-enable-ssr.md

@@ -23,9 +23,9 @@ ni modern.config.js
 </TabItem>
 </Tabs>
 
-在 `modern.config.js` 中添加如下配置：
+在 `modern.config.ts` 中添加如下配置：
 
-```js title="modern.config.js"
+```typescript title="modern.config.ts"
 import { defineConfig } from '@modern-js/app-tools';
 
 export default defineConfig({

package/zh/tutorials/first-app/c04-es6-plus-and-ts/4.3-compatibility.md

@@ -17,9 +17,9 @@ Modern.js 提供了开箱即用的解决客户端兼容性的能力，支持自
 ? 启用可选功能：启用「基于 UA 的 Polyfill」功能
 ```
 
-接着我们修改 `modern.config.js`，添加以下配置：
+接着我们修改 `modern.config.ts`，添加以下配置：
 
-```js title="modern.config.js"
+```typescript title="modern.config.ts"
 export default defineConfig({
   output: {
     polyfill: 'ua',
@@ -41,9 +41,9 @@ export default defineConfig({
 如果遇到无法识别的浏览器，Modern.js 将会返回全量的 polyfill。
 :::
 
-接下里我们继续修改 `modern.config.js`：
+接下里我们继续修改 `modern.config.ts`：
 
-```js title="modern.config.js"
+```typescript title="modern.config.ts"
 export default defineConfig({
   output: {
     enableModernMode: true,

package/zh/tutorials/first-app/c06-css-and-component/6.4-design-system.md

@@ -10,9 +10,9 @@ title: ​管理 Design System
 
 ## 覆盖默认配置
 
-要覆盖默认的设计系统配置，请在 `modern.config.js` 的 `source.designSystem` 中添加要覆盖的键。
+要覆盖默认的设计系统配置，请在 `modern.config.ts` 的 `source.designSystem` 中添加要覆盖的键。
 
-```js title="modern.config.js"
+```typescript title="modern.config.ts"
 export default defineConfig({
   source: {
     designSystem: {
@@ -39,7 +39,7 @@ export default defineConfig({
 
 例如，如果我们想添加一个额外的断点但保留现有的断点，则可以扩展 `screens` 属性：
 
-```js title="modern.config.js"
+```typescript title="modern.config.ts"
 export default defineConfig({
   source: {
     designSystem: {

package/zh/tutorials/first-app/c07-app-entry/7.3-manage-entries-by-hand.md

@@ -10,9 +10,9 @@ title: 管理应用入口​​​
 
 之前的章节中，我们都是直接修改 `package.json` 中的 `modernConfig` 字段来实现修改配置。
 
-现在，让我们在项目目录下，新建一个 `modern.config.js`（若已新建可忽略），并在里面添加内容：
+现在，让我们在项目目录下，新建一个 `modern.config.ts`（若已新建可忽略），并在里面添加内容：
 
-```js title="modern.config.js"
+```typescript title="modern.config.ts"
 export default defineConfig({
   server: {
     ssr: true,

package/zh/tutorials/first-app/c08-client-side-routing/8.1-code-based-routing.md

@@ -10,7 +10,7 @@ title: 使用自控式路由​​​​
 
 `contacts` 和 `landing-page` 这两个入口，都是通过 CLI 自动创建出来的，在创建过程中我们没有修改入口的默认配置，因此每个入口的客户端路由都是默认开启的。
 
-```js title="modern.config.js"
+```js title="modern.config.ts"
 export default defineConfig({
   runtime: {
     router: true,

package/scripts/gen-config.ts

@@ -1,60 +0,0 @@
-import path from 'path';
-import fs from 'fs-extra';
-
-const tip: Record<string, string> = {
-  zh: '该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考',
-  en: 'This configuration is Modern.js Builder configuration, there may be links that cannot be redirected. for details, please refer to',
-};
-
-const createMarkdown = (
-  summary: {
-    dirname: string;
-    name: string;
-  },
-  key: string,
-) => {
-  const { name, dirname } = summary;
-
-  return `---
-title: ${dirname}.${name}
-sidebar_label: ${name}
-sidebar_position: 1
----
-
-:::info BUILDER
-${
-  tip[key]
-} [${dirname}.${name}](https://modernjs.dev/builder/zh/api/config-${dirname}.html#${dirname}-${name.toLowerCase()})。
-:::
-
-import Main from '@modern-js/builder-doc/${key}/config/${dirname}/${name}.md'
-
-<Main />
-`;
-};
-
-const hyphenateRE = /\B([A-Z]+)/g;
-const hyphenate = function (str: string) {
-  return str.replace(hyphenateRE, '-$1').toLowerCase();
-};
-
-const configPath = 'configure/app';
-
-export const gen = (
-  jsonMap: Record<string, { name: string; dirname: string }[]>,
-) => {
-  Object.keys(jsonMap).forEach(key => {
-    const cwd = process.cwd();
-    const baseDir = path.join(cwd, key, configPath);
-
-    const json = jsonMap[key as 'zh' | 'en'];
-    json.forEach(summary => {
-      const mdDir = path.join(baseDir, summary.dirname);
-      const mdPath = path.join(mdDir, `${hyphenate(summary.name)}.md`);
-      if (!fs.existsSync(mdDir)) {
-        fs.mkdirpSync(mdDir);
-      }
-      fs.writeFileSync(mdPath, createMarkdown(summary, key));
-    });
-  });
-};

package/zh/apis/app/hooks/api/framework/app.md

@@ -1,100 +0,0 @@
----
-title: api/app.[tj]s
-sidebar_position: 2
----
-
-Modern.js 框架写法下，该文件可以定制 API Server 的启动逻辑。在使用 `express`, `nest`, `koa` 时，该文件返回对应框架的实例。
-在使用 `egg` 框架时，该文件返回一个 Boot 类；与 `egg` 框架自身的[约定](https://eggjs.org/zh-cn/basics/app-start.html)相同。
-
-以下为简单示例：
-
-## [Express](https://expressjs.com/)
-
-```ts
-import express from 'express'
-
-const app = express();
-
-app.put('/user', function (req, res) {
-  res.send('Got a PUT request at /user')
-})
-
-app.use(async (req, res, next) => {
-    console.info(`access url: ${req.url}`);
-    next();
-});
-export default app
-```
-
-## [Nest](https://nestjs.com/)
-
-Nest 虽然有定制的启动器，但本质与 Express、Koa 相同，所以应用工程沿用了 Nest 定制启动器的默认入口：`api/main.ts`。
-
-按照 Nest 官方生成器生成的项目结构，在应用工程中使用 Nest 框架写法时，目录结构为：
-
-```markdown
-api
-├── app.controller.ts
-├── app.module.ts
-├── app.service.ts
-├── lambda
-│   └── hello.ts
-└── main.ts
-```
-
-其中 `api/main.ts` 中的内容与 Nest 官方生成器生成模版有所不同，应用工程中支持了两种模式：
-
-不包含内置 Module：
-
-```ts
-import { defineCustom } from '@modern-js/plugin-nest';
-import { NestFactory } from '@nestjs/core';
-import { Module } from '@nestjs/common';
-import { AppModule } from './app.module';
-
-export default NestFactory.create(AppModule);
-```
-
-包含内置 Module：
-
-```ts
-import { defineCustom } from '@modern-js/plugin-nest';
-import { NestFactory } from '@nestjs/core';
-import { Module } from '@nestjs/common';
-import { AppModule } from './app.module';
-
-export default defineCustom(async modules => {
-  @Module({
-    imports: [AppModule, ...modules],
-  })
-  class MainModule {}
-
-  return NestFactory.create(MainModule);
-});
-```
-
-## [Koa](https://koajs.com/)
-
-:::caution 注意
-当没有 `app.ts` 的时候，Modern.js 默认会添加 `koa-body`；当有 `app.ts` 时，需要你自己添加 `koa-body` 解析请求体。
-:::
-
-```ts
-import Koa from 'koa'
-import koaBody from 'koa-body'
-
-const app = new Koa();
-app.use(async (ctx, next) => {
-  console.info(`access url: ${ctx.url}`);
-  await next();
-});
-
-app.use(koaBody());
-
-export default app;
-```
-
-## [Egg](https://eggjs.org/)
-
-使用 Egg 框架时，同样在这个文件中可以自定义启动逻辑；
-但与其他框架不同，egg 中此文件遵循 egg 自身的[规范](https://eggjs.org/zh-cn/basics/app-start.html)，而不是 Modern.js 的约定。

package/zh/apis/app/hooks/server/index.md

@@ -1,14 +0,0 @@
----
-title: server/index.[tj]s
-sidebar_position: 1
----
-
-扩展 Modern.js Server 的文件，在此文件中可以给应用工程启动的 Web Server 添加前置中间件。
-
-目前应用工程支持四种不同的框架中间件：Express、Koa、Egg、Nest，具体使用示例可查看 [hook](/docs/apis/app/runtime/web-server/hook)。
-
-可以对请求和响应进行拦截处理，鉴权与角色、请求预处理、异常兜底等；也可在 Server 的运行流程中（包括路由匹配、资源寻址、头部注入、页面渲染，静态 Web 托管）插入特定的业务逻辑。
-
-:::info 注
-使用自定义 Server 需要在项目下执行 new 命令新建「Server 自定义」源码目录。
-:::

package/zh/apis/app/hooks/src/error.md

@@ -1,10 +0,0 @@
----
-title: src/404/App.[tj]s,src/500/App.[tj]s,src/_error/App.[tj]s
-sidebar_position: 4
----
-
-应用项目错误页面。
-
-Modern.js 约定将 `src/404/App.[tj]s` 为默认的 404 路由入口，`src/500/App.[tj]s`为默认 500 路由入口，`src/_error/App.[tj]s` 为默认错误路由入口。
-
-在服务端渲染的场景下，如果服务端出错，会根据 Error Code 返回对应路由的错误入口页面。

package/zh/apis/app/hooks/src/eslint.md

@@ -1,9 +0,0 @@
----
-title: src/.eslintrc.json
-sidebar_position: 5
----
-
-Modern.js ESLint 全量规则集。
-
-具体规则信息请查看：[ESLint 全量规则集](/docs/guides/advanced-features/eslint)
-

package/zh/apis/app/runtime/app/bootstrap.md

@@ -1,83 +0,0 @@
----
-title: bootstrap
-sidebar_position: 8
----
-
-:::info 补充信息
-用于启动并加载应用。
-```ts
-import { bootstrap } from '@modern-js/runtime';
-```
-:::
-
-:::tip 提示
-- 只有自定义入口，即使用 `index.tsx` 而非 `App.tsx` 时，才需要使用该 API。
-- 需要结合 [`createApp`](./create-app.md) 使用。
-:::
-
-## API
-
-`bootstrap(AppComponent, rootElement) => React.ComponentType<any> | void`
-
-### 参数
-
-- AppComponent：`React.ComponentType<any>`，应用根组件，通过 [`createApp`](./create-app.md) 创建。
-- rootElement：`string`，要挂载的 DOM 根元素 id，如 `"root"`。
-
-## 示例
-
-### 非 `SSR` 页面使用
-
-```tsx
-import { createApp, bootstrap } from '@modern-js/runtime';
-import { router, state } from '@modern-js/runtime/plugins';
-import { effects, autoActions } from '@modern-js/runtime/model';
-
-function App() {
-  return <div>Hello Modern.js</div>
-}
-
-const WrappedApp = createApp({
-  // 传入自定义插件
-  plugins: [
-    router({}),
-    state({
-      plugins: [autoActions(), effects()]
-    })
-  ]
-})(App);
-
-bootstrap(WrappedApp, 'root'));
-```
-
-### `SSR` 页面使用
-
-对于 `SSR` 页面，因为组件代码在浏览器端和服务端都会执行，需要通过 `typeof window !== 'undefined'` 区分环境，并暴露 `serverRender` 供服务端渲染。
-
-```tsx
-import { createApp, bootstrap } from '@modern-js/runtime';
-import { router, state } from '@modern-js/runtime/plugins';
-import { effects, autoActions } from '@modern-js/runtime/model';
-
-function App() {
-  return <div>Hello Modern.js</div>
-}
-
-const WrappedApp = createApp({
-  // 传入自定义插件
-  plugins: [
-    router({}),
-    state({
-      plugins: [autoActions(), effects()]
-    })
-  ]
-})(App);
-
-if (typeof window !== 'undefined') {
-  bootstrap(WrappedApp, 'root');
-}
-
-export function serverRender(context: any) {
-  return bootstrap(WrappedApp, context)
-}
-```

package/zh/apis/app/runtime/app/create-app.md

@@ -1,47 +0,0 @@
----
-sidebar_position: 10
----
-
-# createApp
-
-:::info 补充信息
-用于创建自定义入口，定制插件。
-```ts
-import { createApp } from '@modern-js/runtime';
-```
-:::
-
-## API
-
-`createApp(options) => React.ComponentType<any>`
-
-### 参数
-
-- options：`object`，可选的参数。
-  - [plugins]：`Plugin[]`，自定义的插件扩展。
-
-## 示例
-
-### 创建自定义入口
-
-详见 [`bootstrap`](./bootstrap.md)。
-
-### 定制插件
-
-```ts
-import { createApp } from '@modern-js/runtime';
-
-function App() {
-  return <div>app</div>;
-}
-
-export default createApp({
-  plugins: [
-    router({}),
-    state({
-      plugins: [autoActions(), effects()]
-    })
-  ]
-})(App)
-
-```