@modern-js/main-doc 0.0.0-next-20221116121040

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

@@ -0,0 +1,226 @@
+---
+sidebar_label: ssg
+---
+# output.ssg
+
+
+
+* 类型： `boolean` | `object` | `function`
+* 默认值： `undefined`
+
+开启**自控式路由**或**约定式路由** SSG 功能的配置。
+
+:::info 客户端路由
+相关内容可以查看[自控式路由](/docs/tutorials/first-app/c08-client-side-routing/8.1-code-based-routing)或[约定式路由](/docs/tutorials/first-app/c08-client-side-routing/8.2-file-based-routing)。
+:::
+
+## 示例
+
+### 单入口
+
+当该配置设置为 `true` 时，将会默认开启所有入口的 SSG 功能。
+
+对**自控式路由**而言，将会渲染入口路由。对**约定式路由**而言，将会渲染入口中每一条客户端路由。
+
+例如 `src/` 目录下有以下满足**约定式路由**的文件结构：
+
+```bash
+.
+├── pages/
+│   ├── user/
+│   │   └── info.tsx
+│   ├── home.tsx
+│   └── index.tsx
+├── .eslintrc.json
+```
+
+在 `modern.js.config` 中做以下设置：
+
+```js
+module.exports = {
+  output: {
+    ssg: true,
+  },
+};
+```
+
+执行 `pnpm build` 构建应用后。`dist/` 目录将会生成三张 HTML 分别对应三条路由（不开启 SSG 时只有一张 HTML 对应主入口），并且可以看到所有 HTML 都已经是渲染之后的。
+
+而例如下面的**自控式路由**：
+
+```ts title="App.tsx"
+import { Switch, Route } from '@modern-js/runtime/router';
+
+export default () => (
+  <Switch>
+    <Route path="/" exact={true}>
+      <div>Home</div>
+    </Route>
+    <Route path="/foo" exact={true}>
+      <div>Foo</div>
+    </Route>
+  </Switch>
+);
+```
+
+同样使用上面的配置，在执行 `pnpm build` 后，只有入口路由 `/` 会生成渲染后的 HTML。
+
+### 多入口
+
+`output.ssg` 也可以按照入口配置，配置生效的规则同样由入口路由方式决定。
+
+例如以下目录结构：
+
+```bash
+.
+├── src/
+│   ├── contacts/
+│   │   └── App.tsx
+│   ├── landing-page/
+│   │   └── pages/
+│   │       ├── [user].tsx
+│   │       ├── docs.tsx
+│   │       └── index.tsx
+```
+
+默认情况下，所有约定式路由的入口，在设置 `output.ssg` 配置后都会在构建阶段渲染，可以配置 `false` 来取消指定入口的的默认行为，例如取消上述 landing-page 入口在构建时的渲染：
+
+```js
+module.exports = {
+  output: {
+    ssg: {
+      contacts: true,
+      'landing-page': false,
+    },
+  },
+};
+```
+
+### 配置路由
+
+上述内容中提到，**自控式路由**默认只会开启入口路由的 SSG 配置。
+
+可以在 `output.ssg` 中设置具体的路由，告知 Modern.js 开启这些客户端路由的 SSG 功能。例如上述 `contacts/App.tsx` 的文件内容为：
+
+```ts title="contacts/App.tsx"
+import { Switch, Route } from '@modern-js/runtime/router';
+
+export default () => (
+  <Switch>
+    <Route path="/" exact={true}>
+      <div>Home</div>
+    </Route>
+    <Route path="/foo" exact={true}>
+      <div>Foo</div>
+    </Route>
+  </Switch>
+);
+```
+
+在 `modern.config.js` 中这样设置后，`/foo` 路由也会开启 SSG 功能：
+
+```js
+module.exports = {
+  output: {
+    ssg: {
+      contacts: {
+        routes: ['/', '/foo'],
+      },
+    },
+  },
+};
+```
+
+Modern.js 将会自动根据入口拼接完整的 URL 并交给 SSG 插件完成渲染。
+
+也可以为具体入口或路由配置请求头，例如：
+
+```js
+module.exports = {
+  output: {
+    ssg: {
+      contacts: {
+        headers: {},
+        routes: [
+          '/',
+          {
+            url: '/foo',
+            headers: {},
+          },
+        ],
+      },
+    },
+  },
+};
+```
+
+:::info
+路由中设置的 `headers` 会覆盖入口中设置的 `headers`。
+:::
+
+### 阻止默认行为
+
+**约定式路由**也可以通过配置的方式来开启指定路由的 SSG。
+
+但因为默认行为的不同，这里为**约定式路由**提供了另一个字段，用来阻止默认的 SSG 行为。
+
+例如以下目录结构，除了 `/docs4` 外的所有 landing-page 入口中的路由都开启 SSG：
+
+```bash
+.
+├── src/
+│   ├── contacts/
+│   │   └── App.tsx
+│   ├── landing-page/
+│   │   └── pages/
+│   │       ├── [user].tsx
+│   │       ├── docs.tsx
+│   │       ├── docs1.tsx
+│   │       ├── docs2.tsx
+│   │       ├── docs3.tsx
+│   │       ├── docs4.tsx
+│   │       └── index.tsx
+```
+
+可以这样设置，禁用某一条客户端路由的默认行为：
+
+:::info 注
+该配置仅在渲染动态路径的约定式路由时使用。
+:::
+
+```js
+module.exports = {
+  output: {
+    'landing-page': {
+      preventDefault: ['/docs4'],
+    },
+  },
+};
+```
+
+### 添加动态路由参数
+
+部分路由可能是动态的，例如自控式路由中的 `/user/:id` 或是约定式路由中 `user/[id].ts` 文件生成的路由。
+
+可以在 `output.ssg` 中配置具体的参数，渲染指定参数的路由，例如：
+
+```js
+module.exports = {
+  output: {
+    ssg: {
+      'landing-page': {
+        routes: [
+          {
+            url: '/user/:id',
+            params: [
+              {
+                id: 'modernjs',
+              },
+            ],
+          },
+        ],
+      },
+    },
+  },
+};
+```

package/zh/configure/app/output/svg-default-export.md

@@ -0,0 +1,13 @@
+---
+title: output.svgDefaultExport
+sidebar_label: svgDefaultExport
+sidebar_position: 1
+---
+
+:::info BUILDER
+该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [output.svgDefaultExport](https://modernjs.dev/builder/zh/api/config-output.html#output-svgdefaultexport)。
+:::
+
+import Main from '@modern-js/builder-doc/zh/config/output/svgDefaultExport.md'
+
+<Main />

package/zh/configure/app/performance/build-cache.md

@@ -0,0 +1,13 @@
+---
+title: performance.buildCache
+sidebar_label: buildCache
+sidebar_position: 1
+---
+
+:::info BUILDER
+该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [performance.buildCache](https://modernjs.dev/builder/zh/api/config-performance.html#performance-buildcache)。
+:::
+
+import Main from '@modern-js/builder-doc/zh/config/performance/buildCache.md'
+
+<Main />

package/zh/configure/app/performance/bundle-analyze.md

@@ -0,0 +1,13 @@
+---
+title: performance.bundleAnalyze
+sidebar_label: bundleAnalyze
+sidebar_position: 1
+---
+
+:::info BUILDER
+该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [performance.bundleAnalyze](https://modernjs.dev/builder/zh/api/config-performance.html#performance-bundleanalyze)。
+:::
+
+import Main from '@modern-js/builder-doc/zh/config/performance/bundleAnalyze.md'
+
+<Main />

package/zh/configure/app/performance/chunk-split.md

@@ -0,0 +1,13 @@
+---
+title: performance.chunkSplit
+sidebar_label: chunkSplit
+sidebar_position: 1
+---
+
+:::info BUILDER
+该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [performance.chunkSplit](https://modernjs.dev/builder/zh/api/config-performance.html#performance-chunksplit)。
+:::
+
+import Main from '@modern-js/builder-doc/zh/config/performance/chunkSplit.md'
+
+<Main />

package/zh/configure/app/performance/print-file-size.md

@@ -0,0 +1,13 @@
+---
+title: performance.printFileSize
+sidebar_label: printFileSize
+sidebar_position: 1
+---
+
+:::info BUILDER
+该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [performance.printFileSize](https://modernjs.dev/builder/zh/api/config-performance.html#performance-printfilesize)。
+:::
+
+import Main from '@modern-js/builder-doc/zh/config/performance/printFileSize.md'
+
+<Main />

package/zh/configure/app/performance/profile.md

@@ -0,0 +1,13 @@
+---
+title: performance.profile
+sidebar_label: profile
+sidebar_position: 1
+---
+
+:::info BUILDER
+该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [performance.profile](https://modernjs.dev/builder/zh/api/config-performance.html#performance-profile)。
+:::
+
+import Main from '@modern-js/builder-doc/zh/config/performance/profile.md'
+
+<Main />

package/zh/configure/app/performance/remove-console.md

@@ -0,0 +1,13 @@
+---
+title: performance.removeConsole
+sidebar_label: removeConsole
+sidebar_position: 1
+---
+
+:::info BUILDER
+该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [performance.removeConsole](https://modernjs.dev/builder/zh/api/config-performance.html#performance-removeconsole)。
+:::
+
+import Main from '@modern-js/builder-doc/zh/config/performance/removeConsole.md'
+
+<Main />

package/zh/configure/app/performance/remove-moment-locale.md

@@ -0,0 +1,13 @@
+---
+title: performance.removeMomentLocale
+sidebar_label: removeMomentLocale
+sidebar_position: 1
+---
+
+:::info BUILDER
+该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [performance.removeMomentLocale](https://modernjs.dev/builder/zh/api/config-performance.html#performance-removemomentlocale)。
+:::
+
+import Main from '@modern-js/builder-doc/zh/config/performance/removeMomentLocale.md'
+
+<Main />

package/zh/configure/app/plugins.md

@@ -0,0 +1,74 @@
+---
+title: plugins (插件)
+sidebar_position: 9
+---
+
+- 类型： `CliPlugin[] | { cli: CliPlugin[] }`
+- 默认值：`[]`
+
+用于配置自定义的 Modern.js 插件。
+
+自定义插件的编写方式请参考 [如何编写插件](/docs/guides/topic-detail/framework-plugin/implement)。
+
+该选项用于配置框架插件，如果需要配置 webpack 插件，请使用 [tools.webpack](/docs/configure/app/tools/webpack) 或 [tools.webpackChain](/docs/configure/app/tools/webpack-chain); 需要配置 babel 插件，请使用 [tools.babel](/docs/configure/app/tools/babel)。
+
+## 插件类型
+
+Modern.js 中内置了三种不同的插件机制：
+
+- `CLI 插件`，适用于本地开发、编译构建阶段，可以在命令行和编译阶段扩展各种能力。
+- `Server 插件`，适用于服务端。
+- `Runtime 插件`，适用于前端运行时。
+
+目前 Modern.js 开放了自定义 CLI 插件的能力，Server 插件和 Runtime 插件会在后续开放。
+
+## 插件执行顺序
+
+默认情况下，自定义插件会按照 `plugins` 数组的顺序依次执行，Modern.js 内置插件的执行时机早于自定义插件。
+
+当插件内部使用了控制顺序的相关字段，比如 `pre`、`post` 时，会基于声明的字段对执行顺序进行调整，详见 [插件之间的关系](/docs/guides/topic-detail/framework-plugin/relationship)。
+
+## 示例
+
+下面是 CLI 插件的使用示例。
+
+### 使用 npm 上的插件
+
+使用 npm 上的插件，需要通过包管理器安装插件，并通过 import 引入。
+
+```ts title="modern.config.ts"
+import MyPlugin from 'my-plugin';
+
+export default defineConfig({
+  plugins: [MyPlugin()],
+});
+```
+
+### 使用本地插件
+
+使用本地代码仓库中的插件，直接通过相对路径 import 引入即可。
+
+```ts title="modern.config.ts"
+import MyPlugin from './config/plugin/MyPlugin';
+
+export default defineConfig({
+  plugins: [MyPlugin()],
+});
+```
+
+### 插件配置项
+
+如果插件提供了一些自定义的配置项，可以通过插件函数的参数传入配置。
+
+```ts title="modern.config.ts"
+import MyPlugin from 'my-plugin';
+
+export default defineConfig({
+  plugins: [
+    MyPlugin({
+      foo: 1,
+      bar: 2,
+    }),
+  ],
+});
+```

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

@@ -0,0 +1,4 @@
+{
+  "label": "runtime (运行时)",
+  "position": 3
+}

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

@@ -0,0 +1,72 @@
+---
+sidebar_label: masterApp
+sidebar_position: 3
+---
+
+# runtime.masterApp
+
+
+
+* 类型： `Object`
+
+:::tip 提示
+```ts
+export declare type Config = Partial<GarfishOptions> & {
+  manifest: {
+    modules: Array<{
+        name: string;
+        entry: string;
+        activeWhen?: string;
+      }> | string;
+  };
+  LoadingComponent?: React.ComponentType | React.ElementType;
+};
+```
+:::
+
+## `manifest`
+
+- 类型：`modules: Array<{
+        name: string;
+        entry: string;
+        activeWhen?: string;
+      }> | string;`
+- 默认值：`null`
+
+### `modules`
+
+当 `modules` 为对象类型的时候，表示子应用模块的信息。
+
+- name: 子应用的名称。
+- entry: 子应用的入口。
+- activeWhen?: 子应用激活路径。
+
+当 `modules` 为 `string` 时，是一个 url 地址，请求该地址可以拿到和 `modules` 对象格式一样的数据结构。
+
+## `LoadingComponent`
+
+- 类型: `React.ComponentType | React.ElementType`
+- 默认值 `null`
+
+当加载或切换子应用的时候，加载的过渡动画。
+
+`LoadingComponent` 需要通过 [defineConfig](/docs/apis/app/runtime/app/define-config) 配置。
+
+```tsx
+import { defineConfig } from '@modern-js/runtime';
+
+function App() {
+  ...
+}
+
+defineConfig(
+  App,
+  {
+    masterApp: {
+      LoadingComponent: () => {
+        return <div>loading...</div>
+      }
+    }
+  }
+)
+```

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

@@ -0,0 +1,54 @@
+---
+sidebar_label: router
+sidebar_position: 1
+---
+
+# runtime.router
+
+
+
+* 类型： `Object`
+* 默认值： 默认会根据当前入口访问路由设置 `historyOptions.basename`。
+
+:::tip 提示
+
+```ts
+export interface BrowserHistoryBuildOptions {
+    basename?: string | undefined;
+    forceRefresh?: boolean | undefined;
+    getUserConfirmation?: typeof getConfirmation | undefined;
+    keyLength?: number | undefined;
+}
+
+export interface HashHistoryBuildOptions {
+    basename?: string | undefined;
+    hashType?: HashType | undefined;
+    getUserConfirmation?: typeof getConfirmation | undefined;
+}
+
+export type RouterConfig =  {
+      supportHtml5History: true;
+      historyOptions: BrowserHistoryBuildOptions;
+   }
+  | {
+      supportHtml5History: false;
+      historyOptions: HashHistoryBuildOptions;
+    }
+```
+:::
+
+具体配置选项解释如下:
+
+### supportHtml5History
+
+* 类型： `Boolean`
+* 默认值： `true`
+
+值为 `true` 则使用 `BrowserRouter` 否则使用 `HashRouter`。
+
+### historyOptions
+
+* 类型： `BrowserHistoryBuildOptions | HashHistoryBuildOptions`
+* 默认值： 默认会根据当前入口路由设置 basename。
+
+historyOptions 具体配置可以参考: [history](https://github.com/remix-run/history/blob/v4/docs/Misc.md)

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

@@ -0,0 +1,45 @@
+---
+sidebar_label: state
+sidebar_position: 2
+---
+
+# runtime.state
+
+
+
+- 类型：`boolean | object`
+- 默认值：`false`
+
+开启 `state` 后就可以使用 [Model](/docs/guides/topic-detail/model/quick-start) 来做状态管理。
+
+
+具体配置项如下：
+
+## `immer`
+
+- 类型：`boolean`
+- 默认值：`true`
+
+是否启用以 mutable 更新 state 的方式，默认启用，若想禁用则设置为 `false`。
+
+## `effects`
+
+- 类型：`boolean`
+- 默认值：`true`
+
+是否启用副作用管理特性，默认启用，若想禁用则设置为 `false`。
+
+## `autoActions`
+
+- 类型：`boolean`
+- 默认值：`true`
+
+是否启用自动生成 actions 特性，默认启用，若想禁用则设置为 `false`。
+
+
+## `devtools`
+
+- 类型：`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

@@ -0,0 +1,13 @@
+---
+title: security.sri
+sidebar_label: sri
+sidebar_position: 1
+---
+
+:::info BUILDER
+该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [security.sri](https://modernjs.dev/builder/zh/api/config-security.html#security-sri)。
+:::
+
+import Main from '@modern-js/builder-doc/zh/config/security/sri.md'
+
+<Main />

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

@@ -0,0 +1,4 @@
+{
+  "label": "server (服务器)",
+  "position": 4
+}

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

@@ -0,0 +1,36 @@
+---
+sidebar_label: baseUrl
+sidebar_position: 3
+---
+
+# server.baseUrl
+
+
+
+* 类型： `string | string[]`
+* 默认值： `undefined`
+
+
+统一设置服务端路由前缀（常用于共享域名的情况，区分流量)。
+
+```js title="modern.config.js"
+export default defineConfig({
+  server: {
+    // 所有生成的路由前面都会自动加上前缀 `/base`
+    // 生成的服务端路由文件路径：dist/route.json
+    baseUrl: '/base'
+
+    // 多 baseUrl
+    baseUrl: ['/base-new', '/base-old']
+  }
+})
+```
+
+`dev` 之后可以看到路由访问会加上对应前缀:
+
+```bash
+App running at:
+
+  > Local:    http://localhost:8080/base/
+  > Network:  http://192.168.0.1:8080/base/
+```

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

@@ -0,0 +1,21 @@
+---
+sidebar_label: port
+sidebar_position: 5
+---
+
+# server.port
+
+
+
+* 类型： `Number`
+* 默认值： `8080`
+
+Modern.js 在 `dev` 和  `start` 时会以 `8080` 为默认端口启动，通过该配置可以修改 Server 启动的端口号:
+
+```js title="modern.config.js"
+export default defineConfig({
+  server: {
+    port: 3000,
+  }
+});
+```