@modern-js/main-doc 2.0.2 → 2.1.0

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

@@ -11,7 +11,7 @@ sidebar_position: 1
 
 ### runtime
 
-* 类型：`Object`
+- 类型：`Object`
 
 runtime 配置方式如下：
 
@@ -25,8 +25,8 @@ import { defineConfig } from '@modern-js/app-tools';
 export default defineConfig({
   runtime: {
     state: true,
-    router: true
-  }
+    router: true,
+  },
 });
 ```
 
@@ -38,6 +38,28 @@ export default defineConfig({
 当 runtime 配置中存在函数时，只能使用该方式进行配置。
 :::
 
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<Tabs>
+  <TabItem value="layout" label="约定式路由" default>
+
+```tsx title="src/routes/layout.tsx"
+import type { AppConfig } from '@modern-js/runtime';
+
+export const config = (): AppConfig => {
+  return {
+    router: {
+      supportHtml5History: false
+    }
+  }
+};
+```
+
+  </TabItem>
+
+  <TabItem value="app" label="自控路由">
+
 ```ts title="src/App.tsx"
 import { defineConfig } from '@modern-js/runtime';
 
@@ -47,13 +69,18 @@ const App = () => {
 
 defineConfig(App, {
   router: {
-    supportHtml5History: false
-  }
-})
+    supportHtml5History: false,
+  },
+});
 
 export default App;
 ```
 
+  </TabItem>
+</Tabs>
+
+
+
 :::info
 使用运行时配置，可以解决 Runtime 插件配置需要在运行时才能获取到具体内容问题。
 
@@ -66,8 +93,8 @@ defineConfig 中只能定义 Runtime 插件的具体配置内容，确认是否
 
 ### runtimeByEntries
 
-* 类型： `Object`
-* 默认值：无
+- 类型： `Object`
+- 默认值：无
 
 #### 说明
 
@@ -82,10 +109,11 @@ export default defineConfig({
   },
   runtimeByEntries: {
     entry1: {
-       state: true, // { state: true }
+      state: true, // { state: true }
     },
-    entry2: { // { state: false, router: true }
-       router: true,
+    entry2: {
+      // { state: false, router: true }
+      router: true,
     },
   },
 });

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

@@ -4,7 +4,7 @@ sidebar_label: masterApp
 
 # runtime.masterApp
 
-* 类型： `Object`
+- 类型： `Object`
 
 :::info
 需要先通过 `pnpm run new` 启用「微前端」 功能。
@@ -18,7 +18,6 @@ import MasterManifestAppConfig from '@site-docs/components/micro-master-manifest
 <EnableMicroFrontend />
 <MasterManifestAppConfig />
 
-
 ### apps
 
 当 `apps` 为对象类型的时候，表示子应用模块的信息 `Array<AppInfo>`

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

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

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

@@ -4,52 +4,51 @@ sidebar_label: state
 
 # runtime.state
 
-* 类型：`boolean | object`
-* 默认值：`false`
+- 类型：`boolean | object`
+- 默认值：`false`
 
 开启 `state` 后就可以使用 [Model](/docs/guides/topic-detail/model/quick-start) 来做状态管理。
 
-
 具体配置项如下：
 
 ## models
 
-* 类型：`Array<Model>`
-* 默认值：`[]`
+- 类型：`Array<Model>`
+- 默认值：`[]`
 
 注册提前挂载的 model 对象，这些 model 会在 Reduck store 创建完成后立即执行挂载。一般使用无需提前挂载。
 
 ## initialState
-* 类型: `Object`
-* 默认值：`{}`
+
+- 类型: `Object`
+- 默认值：`{}`
 
 用于设置全局 store 的初始状态。一般用于 SSR 在 hydration 阶段初始化数据。
 
 ## immer
 
-* 类型：`boolean`
-* 默认值：`true`
+- 类型：`boolean`
+- 默认值：`true`
 
 是否启用以 mutable 更新 state 的方式，默认启用，若想禁用则设置为 `false`。
 
 ## effects
 
-* 类型：`boolean`
-* 默认值：`true`
+- 类型：`boolean`
+- 默认值：`true`
 
 是否启用副作用管理特性，默认启用，若想禁用则设置为 `false`。
 
 ## autoActions
 
-* 类型：`boolean`
-* 默认值：`true`
+- 类型：`boolean`
+- 默认值：`true`
 
 是否启用自动生成 actions 特性，默认启用，若想禁用则设置为 `false`。
 
-
 ## devtools
 
-* 类型：`boolean | EnhancerOptions`
-* 默认值：`true`
+- 类型：`boolean | EnhancerOptions`
+- 默认值：`true`
 
 是否启用 devtools，默认启用，同时支持 [redux-devtools-extension](https://github.com/zalmoxisus/redux-devtools-extension/blob/master/docs/API/Arguments.md) 的所有参数，若想禁用则设置为 `false`。

package/zh/configure/app/security/sri.md

@@ -4,9 +4,9 @@ sidebar_label: sri
 ---
 
 :::info BUILDER
-该配置为 Modern.js Builder 配置，详细信息可参考 [security.sri](https://modernjs.dev/builder/zh/api/config-security.html#security-sri)。
+该配置为 Modern.js Builder 配置，详细信息可参考 [security.sri](https://modernjs.dev/builder/api/config-security.html#security-sri)。
 :::
 
-import Main from '@modern-js/builder-doc/zh/config/security/sri.md'
+import Main from '@modern-js/builder-doc/docs/zh/config/security/sri.md'
 
 <Main />

package/zh/configure/app/server/base-url.md

@@ -4,15 +4,12 @@ sidebar_label: baseUrl
 
 # server.baseUrl
 
-
-
-* 类型： `string | string[]`
-* 默认值： `undefined`
-
+- 类型： `string | string[]`
+- 默认值： `undefined`
 
 统一设置服务端路由前缀（常用于共享域名的情况，区分流量)。
 
-```typescript title="modern.config.ts"
+```ts title="modern.config.ts"
 export default defineConfig({
   server: {
     // 所有生成的路由前面都会自动加上前缀 `/base`

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

@@ -1,20 +1,21 @@
 ---
 sidebar_label: enableFrameworkExt
 ---
+
 # server.enableFrameworkExt
 
-* 类型： `Boolean`
-* 默认值： `false`
+- 类型： `boolean`
+- 默认值： `false`
 
 默认情况下，开启[自定义 Web Server 功能](/docs/guides/advanced-features/web-server)后，Middleware 会使用 Modern.js 本身的语法。
 
 开启 `server.enableFrameworkExt` 可以使用其他框架扩展的语法。
 
-```typescript title="modern.config.ts"
+```ts title="modern.config.ts"
 export default defineConfig({
   server: {
     enableFrameworkExt: true,
-  }
+  },
 });
 ```
 

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

@@ -4,17 +4,35 @@ sidebar_label: port
 
 # server.port
 
+- 类型： `number`
+- 默认值： `8080`
 
+Modern.js 在执行 `dev`, `start` 和 `serve` 命令时，会以 `8080` 为默认端口启动，并会在端口被占用时自动递增端口号。你可以通过该配置来修改 Server 启动的端口号：
 
-* 类型： `Number`
-* 默认值： `8080`
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    port: 3000,
+  },
+});
+```
 
-Modern.js 在 `dev` 和  `start` 时会以 `8080` 为默认端口启动，通过该配置可以修改 Server 启动的端口号：
+### 与 dev.port 的区别
 
-```typescript title="modern.config.ts"
+大多数情况下，我们推荐使用 `server.port` 而不是 `dev.port` 来设置端口号，他们之间的区别如下：
+
+- `dev.port` 仅在开发环境下生效，`server.port` 在开发环境和生产环境下均能生效。
+- 在开发环境下，`dev.port` 的优先级高于 `server.port`。
+
+当你同时设置 `dev.port` 和 `server.port` 时，`dev.port` 会在开发环境下生效，`server.port` 会在生产环境下生效。比如以下例子，在开发环境下监听的端口号为 `3001`，在生产环境下监听的端口号为 `3002`。
+
+```ts title="modern.config.ts"
 export default defineConfig({
+  dev: {
+    port: 3001,
+  },
   server: {
-    port: 3000,
-  }
+    port: 3002,
+  },
 });
 ```

package/zh/configure/app/server/public-routes.md

@@ -4,16 +4,14 @@ sidebar_label: publicRoutes
 
 # server.publicRoutes
 
-
-
-* 类型： `Object`
-* 默认值： 根据文件约定自动生成的服务端路由规则：应用的每个文件生成一条路由规则。
+- 类型： `Object`
+- 默认值： 根据文件约定自动生成的服务端路由规则：应用的每个文件生成一条路由规则。
 
 该配置选项只作用于服务端路由，可以自定义 `config/public/` 下资源的访问路由。
 
 对象的 `key` 为当前应用的相对文件路径（不使用 `./`）, 值可以是 `string`。
 
-```typescript title="modern.config.ts"
+```ts title="modern.config.ts"
 export default defineConfig({
   server: {
     publicRoutes: {
@@ -21,8 +19,8 @@ export default defineConfig({
       'index.json': '/user-config/card-info/extra/help.json',
 
       // 设置一个不带后缀的路由
-      'robot.txt': '/app/authentication'
-    }
-  }
+      'robot.txt': '/app/authentication',
+    },
+  },
 });
 ```

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

@@ -4,8 +4,8 @@ sidebar_label: routes
 
 # server.routes
 
-* 类型： `Object`
-* 默认值： 根据文件约定自动生成的服务端路由规则：应用的每个入口生成一条路由规则，入口名称等于路由名称。
+- 类型： `Object`
+- 默认值： 根据文件约定自动生成的服务端路由规则：应用的每个入口生成一条路由规则，入口名称等于路由名称。
 
 该配置选项只作用于服务端路由，可以自定义应用入口的服务访问配置。
 
@@ -15,7 +15,7 @@ sidebar_label: routes
 
 当值类型为 `string` 时，当前值即表示访问该入口的路由名称。
 
-```typescript title="modern.config.ts"
+```ts title="modern.config.ts"
 export default defineConfig({
   server: {
     routes: {
@@ -30,7 +30,7 @@ export default defineConfig({
 
 也可以通过 `Array<string>` 为入口设置多个访问路由:
 
-```typescript title="modern.config.ts"
+```ts title="modern.config.ts"
 export default defineConfig({
   server: {
     routes: {
@@ -60,7 +60,7 @@ export default defineConfig({
       "entryPath": "html/page-a/index.html",
       "isSPA": true,
       "isSSR": false
-    },
+    }
   ]
 }
 ```
@@ -69,7 +69,7 @@ export default defineConfig({
 
 可以通过配置入口的 resHeaders 设置响应头：
 
-```typescript title="modern.config.ts"
+```ts title="modern.config.ts"
 export default defineConfig({
   server: {
     routes: {

package/zh/configure/app/server/ssr-by-entries.md

@@ -4,10 +4,8 @@ sidebar_label: ssrByEntries
 
 # server.ssrByEntries
 
-
-
-* 类型： `Object`
-* 默认值： `undefined`
+- 类型： `Object`
+- 默认值： `undefined`
 
 按入口设置 ssr 选项，选项内的属性同 [ssr](./ssr.md)，指定值会和 ssr 属性内容做替换合并操作，例如：
 
@@ -15,17 +13,16 @@ sidebar_label: ssrByEntries
 「 入口名 」默认为目录名，少数情况下通过 `source.entries` 自定义入口时，入口名为 `source.entries` 对象的 `key`。
 :::
 
-```typescript title="modern.config.ts"
+```ts title="modern.config.ts"
 export default defineConfig({
   server: {
     ssr: true,
     ssrByEntries: {
       // page-a 不启用 ssr
       'page-a': false,
-    }
-  }
+    },
+  },
 });
 ```
 
 如上配置，项目整体启用了 ssr, 但是针对入口 `page-a` 关闭了 ssr 渲染能力。
-

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

@@ -4,18 +4,17 @@ sidebar_label: ssr
 
 # server.ssr
 
-* 类型： `boolean`
-* 默认值： `false`
+- 类型： `boolean`
+- 默认值： `false`
 
 SSR 开关以及相关设置。
 
 当值类型为 `boolean` 时，表示是否开启 SSR 部署模式，默认 `false` 不开启。
 
-```typescript title="modern.config.ts"
+```ts title="modern.config.ts"
 export default defineConfig({
   server: {
     ssr: true,
-  }
+  },
 });
 ```
-

package/zh/configure/app/source/alias.md

@@ -4,9 +4,9 @@ sidebar_label: alias
 ---
 
 :::info BUILDER
-该配置为 Modern.js Builder 配置，详细信息可参考 [source.alias](https://modernjs.dev/builder/zh/api/config-source.html#source-alias)。
+该配置为 Modern.js Builder 配置，详细信息可参考 [source.alias](https://modernjs.dev/builder/api/config-source.html#source-alias)。
 :::
 
-import Main from '@modern-js/builder-doc/zh/config/source/alias.md'
+import Main from '@modern-js/builder-doc/docs/zh/config/source/alias.md'
 
 <Main />

package/zh/configure/app/source/compile-js-data-uri.md

@@ -4,9 +4,9 @@ sidebar_label: compileJsDataURI
 ---
 
 :::info BUILDER
-该配置为 Modern.js Builder 配置，详细信息可参考 [source.compileJsDataURI](https://modernjs.dev/builder/zh/api/config-source.html#source-compilejsdatauri)。
+该配置为 Modern.js Builder 配置，详细信息可参考 [source.compileJsDataURI](https://modernjs.dev/builder/api/config-source.html#source-compilejsdatauri)。
 :::
 
-import Main from '@modern-js/builder-doc/zh/config/source/compileJsDataURI.md'
+import Main from '@modern-js/builder-doc/docs/zh/config/source/compileJsDataURI.md'
 
 <Main />

package/zh/configure/app/source/config-dir.md

@@ -3,8 +3,8 @@ title: source.configDir
 sidebar_label: configDir
 ---
 
-* 类型： `string`
-* 默认值： `./config`
+- 类型： `string`
+- 默认值： `./config`
 
 Modern.js 支持在 `./config` 文件夹下放置一些文件自定义 HTML 模板、图标、静态资源等，具体可参考[文件约定](/docs/apis/app/hooks/config/html)。
 

package/zh/configure/app/source/define.md

@@ -4,9 +4,9 @@ sidebar_label: define
 ---
 
 :::info BUILDER
-该配置为 Modern.js Builder 配置，详细信息可参考 [source.define](https://modernjs.dev/builder/zh/api/config-source.html#source-define)。
+该配置为 Modern.js Builder 配置，详细信息可参考 [source.define](https://modernjs.dev/builder/api/config-source.html#source-define)。
 :::
 
-import Main from '@modern-js/builder-doc/zh/config/source/define.md'
+import Main from '@modern-js/builder-doc/docs/zh/config/source/define.md'
 
 <Main />