@modern-js/main-doc 2.0.0-canary.1 → 2.0.1

package/zh/configure/app/auto-load-plugin.md

@@ -0,0 +1,62 @@
+---
+title: autoLoadPlugins (自动注册插件)
+sidebar_position: 11
+---
+
+- 类型：`boolean`
+- 默认值：`false`
+
+用于配置 Modern.js 是否开启自动注册插件。
+
+### 手动注册插件
+
+默认情况下，安装插件后需要你在 `modern.config.ts` 文件中手动注册插件。
+
+```ts title="modern.config.ts"
+import AppToolsPlugin, { defineConfig } from '@modern-js/app-tools';
+import I18nPlugin from '@modern-js/plugin-i18n';
+
+default export defineConfig({
+  plugins: [AppToolsPlugin(), I18nPlugin()]
+})
+
+```
+
+### 自动注册插件
+
+除了手段注册，Modern.js 还提供自动注册插件的方式: 将 `autoLoadPlugin` 配置项置为 `true`。
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+default export defineConfig({
+  autoLoadPlugins: true
+})
+```
+
+Modern.js 将通过以下几个步骤帮你自动注册插件
+
+1. Modern.js 在内部维护一份官方插件列表。
+
+```js
+const InternalPlugins = ['@modern-js/app-tools', '@modern-js/plugin-i18n', ...];
+```
+
+2. Modern.js 将读取你的 `package.json` 文件，收集依赖信息。
+
+```json title="package.json"
+"dependencies": {
+  "@modern-js/plugin-i18n": "x.x.x"
+  ...
+},
+"devDependencies": {
+  "@modern-js/app-tools": "x.x.x"
+  ...
+}
+```
+
+3. Modern.js 观察到你安装了 `@modern-js/plugin-i18n` 和 `@modern-js/app-tools` 等依赖后，将会引入插件自动注册。
+
+可以注意到这种方式相对黑盒，你甚至对加载插件的过程是无感知的。我们希望更多的细节暴露给开发者，能让开发者去控制这一过程。
+
+**因此我们更加推荐你手动注册插件。**

package/zh/configure/app/deploy/microFrontend.md

@@ -52,13 +52,3 @@ export default defineConfig({
 * 默认值：`false`
 
 是否 `external` 基础库，当设置为 `true` 时，当前子应用将会 `external`：`react`、`react-dom`，`EdenX` 主应用会自动 `setExternal` 这两个基础库，如果其他类型的框架请通过 `Garfish.setExternal` 增加 `react`、`react-dom` 依赖
-
-
-### moduleApp
-
-* 类型：`string`
-
-* 默认值：`undefined`
-
-该值可以配置子应用的名称，目前主要结合 [`dev.withMasterApp`](/docs/configure/app/dev/with-master-app) 进行测试。
-

package/zh/configure/app/output/ssg.md

@@ -35,7 +35,7 @@ sidebar_label: ssg
 │               └── page.tsx
 ```
 
-在 `modern.js.config` 中做以下设置：
+在 `modern.config.js` 中做以下设置：
 
 ```js
 export default defineConfig({
@@ -73,10 +73,6 @@ export default () => {
 
 ### 多入口
 
-:::note
-多入口 SSG 暂未支持，敬请期待。
-:::
-
 `output.ssg` 也可以按照入口配置，配置生效的规则同样由入口路由方式决定。
 
 例如以下目录结构：

package/zh/configure/app/runtime/master-app.md

@@ -6,31 +6,17 @@ sidebar_label: masterApp
 
 * 类型： `Object`
 
-:::caution 注意
+:::info
 需要先通过 `pnpm run new` 启用「微前端」 功能。
 :::
 
 ## 示例
 
 import EnableMicroFrontend from '@site-docs/components/enable-micro-frontend.md';
+import MasterManifestAppConfig from '@site-docs/components/micro-master-manifest-config.md';
 
 <EnableMicroFrontend />
-
-## `manifest`
-
-```ts
-interface Manifest {
-  getAppList?: ()=> Array<AppInfo>
-}
-```
-
-#### `getAppList?`
-
-通过 `getAppList` 配置，可以自定义如何获取远程列表数据
-
-```ts
-type GetAppList = ()=> Promise<Array<AppInfo>>;
-```
+<MasterManifestAppConfig />
 
 
 ### apps
@@ -53,4 +39,4 @@ interface AppInfo {
 
 在 `masterApp` 配置下，开发者可以透传 Garfish 的配置项。
 
-所有支持的配置项[点此查看](https://garfishjs.org/api/run/#%E5%8F%82%E6%95%B0)
+所有支持的配置项[点此查看](https://garfishjs.org/api/run/#%E5%8F%82%E6%95%B0)。

package/zh/configure/app/runtime/router.md

@@ -2,19 +2,34 @@
 sidebar_label: router
 ---
 
+import RouterLegacyTip from '@site-docs/components/router-legacy-tip.md'
+
+<RouterLegacyTip />
+
 # runtime.router
 
 * 类型： `boolean | Object`
 * 默认值： `false`。
 
-开启 `router` 之后，支持使用 Modern.js 默认提供的约定式路由进行路由管理。
+开启 `router` 之后，支持使用 Modern.js 默认提供的约定式路由进行路由管理。Modern.js 的路由模块基于 [React Router 6](https://reactrouter.com/) 实现。
 
 具体配置如下：
 
-### supportHtml5History
 
-* 类型： `Boolean`
+## basename
+
+* 类型： `string`
+* 默认值： ``
+
+设置客户端路由的 `basename`，通常用于应用需要部署在域名非根路径下的场景。
+
+## supportHtml5History
+
+* 类型： `boolean`
 * 默认值： `true`
 
-值为 `true` 则使用 `BrowserRouter` 否则使用 `HashRouter`。
+值为 `true`，使用 `BrowserRouter`；否则使用 `HashRouter`。推荐使用 `BrowserRouter`。
 
+:::warning
+当开启 SSR 时，不支持设置 `supportHtml5History`。
+:::

package/zh/configure/app/runtime/state.md

@@ -12,34 +12,34 @@ sidebar_label: state
 
 具体配置项如下：
 
-## `models`
+## models
 
 * 类型：`Array<Model>`
 * 默认值：`[]`
 
 注册提前挂载的 model 对象，这些 model 会在 Reduck store 创建完成后立即执行挂载。一般使用无需提前挂载。
 
-## `initialState`
+## initialState
 * 类型: `Object`
-* * 默认值：`{}`
+* 默认值：`{}`
 
 用于设置全局 store 的初始状态。一般用于 SSR 在 hydration 阶段初始化数据。
 
-## `immer`
+## immer
 
 * 类型：`boolean`
 * 默认值：`true`
 
 是否启用以 mutable 更新 state 的方式，默认启用，若想禁用则设置为 `false`。
 
-## `effects`
+## effects
 
 * 类型：`boolean`
 * 默认值：`true`
 
 是否启用副作用管理特性，默认启用，若想禁用则设置为 `false`。
 
-## `autoActions`
+## autoActions
 
 * 类型：`boolean`
 * 默认值：`true`
@@ -47,7 +47,7 @@ sidebar_label: state
 是否启用自动生成 actions 特性，默认启用，若想禁用则设置为 `false`。
 
 
-## `devtools`
+## devtools
 
 * 类型：`boolean | EnhancerOptions`
 * 默认值：`true`

package/zh/configure/app/server/enable-framework-ext.md

@@ -0,0 +1,47 @@
+---
+sidebar_label: enableFrameworkExt
+---
+# server.enableFrameworkExt
+
+* 类型： `Boolean`
+* 默认值： `false`
+
+默认情况下，开启[自定义 Web Server 功能](/docs/guides/advanced-features/web-server)后，Middleware 会使用 Modern.js 本身的语法。
+
+开启 `server.enableFrameworkExt` 可以使用其他框架扩展的语法。
+
+```typescript title="modern.config.ts"
+export default defineConfig({
+  server: {
+    enableFrameworkExt: true,
+  }
+});
+```
+
+## 示例
+
+默认的使用方式：
+
+```ts title="server/index.ts"
+import { Middleware } from '@modern-js/runtime/server';
+
+export const middleware: Middleware = (ctx, next) => {
+  console.log(ctx.request.url);
+  next();
+};
+```
+
+开启后，Middleware 类型将从其他命名空间下导出，并且可以使用框架拓展的语法：
+
+```ts title="server/index.ts"
+import { SomeType } from '@modern-js/runtime/{frameworknName}';
+
+export const middleware: SomeType = (...args) => {
+  console.log(args[0].url);
+  next();
+};
+```
+
+:::note
+上述代码为伪代码，具体使用方式需要参考对应的框架拓展。
+:::

package/zh/configure/app/server/port.md

@@ -9,7 +9,7 @@ sidebar_label: port
 * 类型： `Number`
 * 默认值： `8080`
 
-Modern.js 在 `dev` 和  `start` 时会以 `8080` 为默认端口启动，通过该配置可以修改 Server 启动的端口号:
+Modern.js 在 `dev` 和  `start` 时会以 `8080` 为默认端口启动，通过该配置可以修改 Server 启动的端口号：
 
 ```typescript title="modern.config.ts"
 export default defineConfig({

package/zh/configure/app/tools/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "tools (底层配置)",
-  "position": 10
+  "position": 12
 }

package/zh/guides/advanced-features/eslint.md

@@ -17,7 +17,8 @@ sidebar_position: 8
 
 :::info 注
 主要在 IDE 保存文件的环节执行这种自动修复，少数漏网之鱼会在提交代码环节被自动修复。
-:::info 注
+:::
+
 ### 批量自动修复
 
 在少数情况下，比如旧项目迁移的时候，可以执行以下命令，批量修复和检查所有文件：

package/zh/guides/advanced-features/ssg.md

@@ -19,6 +19,10 @@ import SSGPlugin from '@modern-js/plugin-ssg';
 // https://modernjs.dev/docs/apis/app/config
 export default defineConfig({
   ...,
+  output: {
+    ...,
+    ssg: true,
+  },
   plugins: [..., SSGPlugin()],
 });
 ```

package/zh/guides/basic-features/data-fetch.md

@@ -425,7 +425,7 @@ export default () => {
     // 这里没有发送真实的请求，只是返回了一个写死的数据。
     // 真实项目中，应该返回从远端获取的数据。
     return {
-      name: 'modern.js',
+      name: 'Modern.js',
     };
   });
 

package/zh/guides/basic-features/env-vars.md

@@ -11,7 +11,7 @@ Modern.js 提供了对环境变量的支持，包含内置的环境变量和自
 
 表示当前的执行环境，是**只读的**的环境变量，其值在不同的执行命令下具有不同的值：
 
-- `production`：执行 `modern build`、`modern preview` 命令时的默认值。
+- `production`：执行 `modern build`、`modern serve` 命令时的默认值。
 - `test`：执行 `modern test` 命令时的默认值。
 - `development`：执行 `modern dev` 命令时的默认值，同时也是其他所有情况下的默认值。
 

package/zh/guides/basic-features/routes.md

@@ -306,9 +306,6 @@ export default () => {
 
 :::note
 在自控式路由下，开发者如果希望在 SSR 中使用 React Router 6 中 [Loader API](https://reactrouter.com/en/main/hooks/use-loader-data#useloaderdata) 的能力会相对复杂，推荐直接使用约定式路由。Modern.js 已经为你封装好了一切。
-
-<!-- Todo 嵌套路由带来的优化可以补充下文档-->
-如果项目只想升级到 React Router 6，而不希望使用嵌套路由带来的优化，那 [useLoader](/docs/apis/app/runtime/core/use-loader) 在 SSR 下仍然可以工作。
 :::
 
 ## 其他路由方案

package/zh/guides/topic-detail/generator/config/module.md

@@ -34,6 +34,8 @@ New 命令的操作类型(actionType)，类型支持一种：
 
 - Tailwind CSS(tailwindcss)
 
-- Storybook(mwa_storybook)
+- Storybook(storybook)
 
 - Runtime API(runtimeApi)
+
+- 测试(test)

package/zh/guides/topic-detail/generator/config/mwa.md

@@ -34,20 +34,12 @@ New 命令的操作类型(actionType)，类型支持两种：
 
 - 新建自定义 Web Serve 源码目录(server)
 
-这两个选项还需要配置具体的配合使用，介绍如下：
+入口还需要配置具体的配合使用，介绍如下：
 
 #### name
 
 入口名称(name), 字符串类型。
 
-#### framework
-
-自定义 Web Serve 运行时框架(framework)，支持两个选项：
-
-- Express(express)
-
-- Koa(koa)
-
 ### function
 
 可选功能名称(function)，支持如下选项:

package/zh/guides/topic-detail/model/quick-start.md

@@ -16,7 +16,7 @@ Reduck 在 MVC 模式中，扮演 M(Model) 的角色，React UI Component 对应
 Modern.js 的状态管理解决方案，是通过内置 Reduck 实现的。在 Modern.js 中使用 Reduck，不仅免去了手动集成的环节，而且所有 Reduck API 都可以从 Modern.js 的 Runtime 包中直接导入使用，具有更好的一致性体验。
 
 :::info 注
-1. Modern.js 中使用 Reduck API，需要设置 [runtime.state](/docs/configure/app/runtime/state) 以开启状态管理功能（默认创建的项目已开启）。
+1. Modern.js 中使用 Reduck API，需要先设置 [runtime.state](/docs/configure/app/runtime/state) 以启用状态管理插件。
 2. Reduck 也可以脱离 Modern.js 作为状态管理库[单独使用](/docs/guides/topic-detail/model/use-out-of-modernjs)。
 :::
 

package/zh/tutorials/first-app/c06-model.md

@@ -6,7 +6,11 @@ title: 添加业务模型（状态管理）
 
 这一章节中，我们会进一步实现项目的功能，例如实现 **Archive** 按钮的功能，把联系人归档。
 
-因此会开始编写一些跟 UI 完全无关的业务逻辑，如果继续写在组件代码中，会产生越来越多的面条式代码。为此，我们引入了一种叫做**业务模型（Model）**的代码模块，将这些业务逻辑和 UI 解耦。
+因此会开始编写一些跟 UI 完全无关的业务逻辑，如果继续写在组件代码中，会产生越来越多的面条式代码。为此，我们引入了一种叫做 **业务模型（Model）** 的代码模块，将这些业务逻辑和 UI 解耦。
+
+:::info 注
+使用 Model API，需要先设置 [runtime.state](/docs/configure/app/runtime/state) 以启用状态管理插件。
+:::
 
 ## 实现 Model
 

package/zh/tutorials/first-app/c08-entries.md

@@ -134,4 +134,4 @@ export default defineConfig({
 
 ## 下一步
 
-接下来你可以通过了解[指南](/docs/guides/overview)、[配置](/docs/configure/app/usage) 等更多教程，进一步完善你的应用。
+接下来你可以通过了解[指南](/docs/guides/get-started/quick-start)、[配置](/docs/configure/app/usage) 等更多教程，进一步完善你的应用。

package/zh/tutorials/foundations/introduction.md

@@ -1,5 +1,5 @@
 ---
-title: Modern.js 介绍
+title: 介绍
 sidebar_position: 1
 ---
 
@@ -36,6 +36,8 @@ Modern.js 能为开发者提供极致的**开发体验（Development Experience
 
 ## 下一步
 
-如果你是前端初学者，可能会觉得这些概念有些复杂。我们提供了一些 [JavaScript 和 React](/docs/tutorials/foundations/basic) 的学习资料，你可以先对它们做些了解。
+<!-- 如果你是前端初学者，可能会觉得这些概念有些复杂。我们提供了一些 [JavaScript 和 React](/docs/tutorials/foundations/basic) 的学习资料，你可以先对它们做些了解。
 
-如果你是有经验的开发者，希望了解如何使用 Modern.js，你可以尝试[创建第一个应用](/docs/tutorials/first-app/c01-start)，或是阅读[指南](/docs/guides/overview)。
+如果你是有经验的开发者，希望了解如何使用 Modern.js，你可以尝试[创建第一个应用](/docs/tutorials/first-app/c01-start)，或是阅读[指南](/docs/guides/get-started/quick-start)。 -->
+
+如果你希望了解如何使用 Modern.js，可以尝试[创建第一个应用](/docs/tutorials/first-app/c01-start)，或是阅读[指南](/docs/guides/get-started/quick-start)。

package/en/docusaurus-plugin-content-docs/current/apis/app/overview.md

@@ -1,12 +0,0 @@
----
-sidebar_position: 0
----
-
-# overview
-
-This section covers all APIs in `@modern-js/app-tools`.
-
-import OverviewNav from '@site/src/components/OverviewNav';
-import sidebarData from '@site/plugins/overview-loader!@site/plugins/overview-data.json';
-
-<OverviewNav cards={sidebarData.docsSidebars.apisAppSidebar} />

package/en/docusaurus-plugin-content-docs/current/configure/app/bff/fetcher.md

@@ -1,28 +0,0 @@
----
-sidebar_label: fetcher
----
-
-# bff.fetcher
-
-* Type: `string`
-* Default:
-  * Brower：[global.fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)
-  * Node.js：[node-fetch](https://github.com/node-fetch/node-fetch)
-
-:::caution Caution
-First you need to enable the "BFF" function using [new](/docs/apis/app/commands/new) command.
-:::
-
-Custom `fetch` function, which can be used for `fetch` function customization in Native and Mini Program scenarios.
-
-```ts title="modern.config.ts"
-export default defineConfig({
-  bff: {
-    fetcher: 'custom-fetch'
-  }
-});
-```
-
-:::info
-You need to judge the running environment when you implement the isomorphic fetch function.
-:::

package/en/docusaurus-plugin-content-docs/current/configure/app/dev/with-master-app.md

@@ -1,31 +0,0 @@
----
-sidebar_label: withMasterApp
----
-
-# dev.withMasterApp
-
-* Type: `Object`
-* Default: `null`
-
-When the project is a micro-front-end sub-application, you can use the `withMasterApp` configuration to enable the sub-application debugging mode.
-
-:::caution Caution
-When using child app debugging mode, you should first ensure that the main app has online debugging mode turned on.
-:::
-
-```js title=modern.config.js
-export default defineConfig({
-  dev: {
-    withMasterApp: {
-      //the path of the main application
-      moduleApp: 'https://www.masterApp.com',
-      //name of the subapplication
-      moduleName: 'Contact'
-    }
-  }
-})
-```
-
-- moduleApp: `string` Online address of the main application.
-- moduleName: `Contact` The name of the child app (needs to match the module name registered in the main app)。
-

package/en/docusaurus-plugin-content-docs/current/guides/overview.md

@@ -1,11 +0,0 @@
----
-sidebar_position: 0
----
-
-# Overview
-
-import OverviewNav from '@site/src/components/OverviewNav';
-
-import sidebarData from '@site/plugins/overview-loader!@site/plugins/overview-data.json';
-
-<OverviewNav cards={sidebarData.docsSidebars.guidesSidebar} />

package/en/docusaurus-plugin-content-docs/current/tutorials/foundations/basic.md

@@ -1,8 +0,0 @@
----
-title: JavaScript & React
-sidebar_position: 2
----
-
-:::note Todo
-Coming Soon...
-:::

package/zh/apis/app/overview.md

@@ -1,11 +0,0 @@
----
-sidebar_position: 0
----
-
-# 概览
-本节涵盖了使用 `@modern-js/app-tools` 的所有 API。
-
-import OverviewNav from '@site/src/components/OverviewNav';
-import sidebarData from '@site/plugins/overview-loader!@site/plugins/overview-data.json';
-
-<OverviewNav cards={sidebarData.docsSidebars.apisAppSidebar} />

package/zh/apis/monorepo/overview.md

@@ -1,11 +0,0 @@
----
-sidebar_position: 0
----
-
-# 概览
-本节涵盖了使用@modern-js/monorepo-tools的所有API。
-
-import OverviewNav from '@site/src/components/OverviewNav';
-import sidebarData from '@site/plugins/overview-loader!@site/plugins/overview-data.json';
-
-<OverviewNav cards={sidebarData.docsSidebars.apisMonorepoSidebar} />

package/zh/configure/app/bff/fetcher.md

@@ -1,31 +0,0 @@
----
-sidebar_label: fetcher
----
-
-# bff.fetcher
-
-
-
-* 类型：`string`
-* 默认值：
-  * 浏览器端：[global.fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)
-  * Node.js 端：[node-fetch](https://github.com/node-fetch/node-fetch)
-
-:::caution 注意
-请先在当前应用项目根目录使用【[new](/docs/apis/app/commands/new)】 启用 BFF 功能。
-:::
-
-
-自定义 `fetch` 函数，可以用于 Native、小程序场景下的 `fetch` 函数定制。
-
-```ts title="modern.config.ts"
-export default defineConfig({
-  bff: {
-    fetcher: 'custom-fetch'
-  }
-});
-```
-
-:::info 注
-这里定制就需要定制两种场景下的 `fetch` 函数，即自行判断运行环境，实现同构的 fetch 函数。
-:::

package/zh/configure/app/dev/with-master-app.md

@@ -1,32 +0,0 @@
----
-sidebar_label: withMasterApp
----
-
-# dev.withMasterApp
-
-
-
-* 类型： `Object`
-* 默认值： `null`
-
-当项目为微前端子应用的时候，可以使用 `withMasterApp` 配置启用子应用调试模式。
-
-:::caution 注意
-使用子应用调试的模式时，应该先确保主应用开启了线上 debug 模式。
-:::
-
-```js title=modern.config.js
-export default defineConfig({
-  dev: {
-    withMasterApp: {
-      // 主应用的路径
-      moduleApp: 'https://www.masterApp.com',
-      // 子应用的名称
-      moduleName: 'Contact'
-    }
-  }
-})
-```
-
-- moduleApp: `string` 主应用的线上地址。
-- moduleName: `Contact` 子应用的名称（需要和在主应用中注册的模块名匹配）。

package/zh/guides/overview.md

@@ -1,11 +0,0 @@
----
-sidebar_position: 0
----
-
-# 概览
-
-import OverviewNav from '@site/src/components/OverviewNav';
-
-import sidebarData from '@site/plugins/overview-loader!@site/plugins/overview-data.json';
-
-<OverviewNav cards={sidebarData.docsSidebars.guidesSidebar} />

package/zh/tutorials/foundations/basic.md

@@ -1,8 +0,0 @@
----
-title: JavaScript & React
-sidebar_position: 2
----
-
-:::note Todo
-敬请期待
-:::