@modern-js/main-doc 2.1.0 → 2.3.0

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

@@ -0,0 +1,196 @@
+---
+sidebar_label: ssg
+---
+
+# output.ssg
+
+- **类型：** `boolean` | `object` | `function`
+- **默认值：** `undefined`
+
+开启**自控式路由**或**约定式路由** SSG 功能的配置。
+
+:::info 客户端路由
+相关内容可以查看[路由](/guides/basic-features/routes)。
+
+:::
+
+## 示例
+
+### 单入口
+
+当该配置设置为 `true` 时，将会默认开启所有入口的 SSG 功能。
+
+对**自控式路由**而言，将会渲染入口的根路由。对**约定式路由**而言，将会渲染入口中每一条路由。
+
+例如 `src/` 目录下有以下满足**约定式路由**的文件结构：
+
+```bash
+.
+├── src
+│   └── routes
+│       ├── layout.tsx
+│       ├── page.tsx
+│       └── user
+│           ├── layout.tsx
+│           ├── page.tsx
+│           └── profile
+│               └── page.tsx
+```
+
+在 `modern.config.js` 中做以下设置：
+
+```js
+export default defineConfig({
+  output: {
+    ssg: true,
+  },
+});
+```
+
+执行 `pnpm build` 构建应用后。`dist/` 目录将会生成三张 HTML 分别对应三条路由（不开启 SSG 时只有一张 HTML），并且所有 HTML 都已经渲染。
+
+而例如下面的**自控式路由**：
+
+import SelfRouteExample from "@site-docs/components/self-route-example";
+
+<SelfRouteExample />
+
+同样使用上面的配置，在执行 `pnpm run build` 后，只有入口路由 `/` 会生成渲染后的 HTML。
+
+### 多入口
+
+`output.ssg` 也可以按照入口配置，配置生效的规则同样由入口路由方式决定。
+
+例如以下目录结构：
+
+```bash
+。
+├── src
+│   ├── entryA
+│   │   └── routes
+│   │       ├── layout.tsx
+│   │       ├── page.tsx
+│   │       └── user
+│   │           ├── layout.tsx
+│   │           ├── page.tsx
+│   │           └── profile
+│   │               └── page.tsx
+│   └── entryB
+│       └── App.tsx
+```
+
+默认情况下，所有约定式路由的入口，在设置 `output.ssg` 配置为 `true` 后都会在构建阶段渲染。可以配置 `false` 来取消指定入口的的默认行为，例如取消上述 entryA 入口在构建时的渲染：
+
+```js
+export default defineConfig({
+  output: {
+    ssg: {
+      entryA: true,
+      entryB: false,
+    },
+  },
+});
+```
+
+### 配置路由
+
+上述内容中提到，**自控式路由**默认只会开启入口路由的 SSG 配置。
+
+可以在 `output.ssg` 中设置具体的路由，告知 Modern.js 开启这些客户端路由的 SSG 功能。例如上述 `src/App.tsx` 的文件内容为：
+
+
+<SelfRouteExample />
+
+在 `modern.config.js` 中这样设置后，`/about` 路由也会开启 SSG 功能：
+
+```js
+export default defineConfig({
+  output: {
+    ssg: {
+      routes: ['/', '/about'],
+    },
+  },
+});
+```
+
+Modern.js 将会自动根据入口拼接完整的 URL 并交给 SSG 插件完成渲染。
+
+也可以为具体入口或路由配置请求头，例如：
+
+```js
+export default defineConfig({
+  output: {
+    ssg: {
+      headers: {},
+      routes: [
+        '/',
+        {
+          url: '/about',
+          headers: {},
+        },
+      ],
+    },
+  },
+});
+```
+
+:::info
+路由中设置的 `headers` 会覆盖入口中设置的 `headers`。
+
+:::
+
+### 阻止默认行为
+
+默认情况下，**约定式路由**的路由会全部开启 SSG。Modern.js 提供了另一个字段，用来阻止默认的 SSG 行为。
+
+例如以下目录结构，`/`、`/user`、`/user/profle` 三条路由都开启 SSG：
+
+```bash
+.
+├── src
+│   └── routes
+│       ├── layout.tsx
+│       ├── page.tsx
+│       └── user
+│           ├── layout.tsx
+│           ├── page.tsx
+│           └── profile
+│               └── page.tsx
+```
+
+可以这样设置，禁用某一条客户端路由的默认行为：
+
+```js
+export default defineConfig({
+  output: {
+    preventDefault: ['/user'],
+  },
+});
+```
+
+### 添加动态路由参数
+
+部分路由可能是动态的，例如自控式路由中的 `/user/:id` 或是约定式路由中 `user/[id]/page.tsx` 文件生成的路由。
+
+可以在 `output.ssg` 中配置具体的参数，渲染指定参数的路由，例如：
+
+```js
+export default defineConfig({
+  output: {
+    ssg: {
+      routes: [
+        {
+          url: '/user/:id',
+          params: [
+            {
+              id: 'modernjs',
+            },
+          ],
+        },
+      ],
+    },
+  },
+});
+```
+
+动态路由和 SSG 的组合，在根据 CMS 系统数据变更，实时生成静态页面时非常有用。

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

@@ -0,0 +1,13 @@
+---
+sidebar_label: svgDefaultExport
+---
+
+# output.svgDefaultExport
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [output.svgDefaultExport](https://modernjs.dev/builder/api/config-output.html#output-svgdefaultexport)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/output/svgDefaultExport.md'
+
+<Main />

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

@@ -0,0 +1,13 @@
+---
+sidebar_label: buildCache
+---
+
+# performance.buildCache
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [performance.buildCache](https://modernjs.dev/builder/api/config-performance.html#performance-buildcache)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/performance/buildCache.md'
+
+<Main />

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

@@ -0,0 +1,13 @@
+---
+sidebar_label: bundleAnalyze
+---
+
+# performance.bundleAnalyze
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [performance.bundleAnalyze](https://modernjs.dev/builder/api/config-performance.html#performance-bundleanalyze)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/performance/bundleAnalyze.md'
+
+<Main />

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

@@ -0,0 +1,13 @@
+---
+sidebar_label: chunkSplit
+---
+
+# performance.chunkSplit
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [performance.chunkSplit](https://modernjs.dev/builder/api/config-performance.html#performance-chunksplit)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/performance/chunkSplit.md'
+
+<Main />

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

@@ -0,0 +1,13 @@
+---
+sidebar_label: printFileSize
+---
+
+# performance.printFileSize
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [performance.printFileSize](https://modernjs.dev/builder/api/config-performance.html#performance-printfilesize)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/performance/printFileSize.md'
+
+<Main />

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

@@ -0,0 +1,13 @@
+---
+sidebar_label: profile
+---
+
+# performance.profile
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [performance.profile](https://modernjs.dev/builder/api/config-performance.html#performance-profile)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/performance/profile.md'
+
+<Main />

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

@@ -0,0 +1,13 @@
+---
+sidebar_label: removeConsole
+---
+
+# performance.removeConsole
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [performance.removeConsole](https://modernjs.dev/builder/api/config-performance.html#performance-removeconsole)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/performance/removeConsole.md'
+
+<Main />

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

@@ -0,0 +1,13 @@
+---
+sidebar_label: removeMomentLocale
+---
+
+# performance.removeMomentLocale
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [performance.removeMomentLocale](https://modernjs.dev/builder/api/config-performance.html#performance-removemomentlocale)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/performance/removeMomentLocale.md'
+
+<Main />

package/zh/configure/app/plugins.mdx

@@ -0,0 +1,81 @@
+---
+title: plugins (插件)
+sidebar_position: 9
+---
+# plugins (插件)
+
+- **类型：** `CliPlugin[]`
+- **默认值：** `[]`
+
+用于配置自定义的 Modern.js 框架插件。
+
+自定义插件的编写方式请参考 [如何编写插件](/guides/topic-detail/framework-plugin/implement)。
+
+## 注意事项
+
+该选项**用于配置框架插件**，如果你需要配置其他类型的插件，请选择对应的配置方式：
+
+- 配置 Modern.js Builder 插件，请使用 [builderPlugins](docs/configure/app/builder-plugins) 配置项。
+- 配置 webpack 插件，请使用 [tools.webpack](/configure/app/tools/webpack) 或 [tools.webpackChain](/configure/app/tools/webpack-chain) 配置项。
+- 配置 Babel 插件，请使用 [tools.babel](/configure/app/tools/babel) 配置项。
+
+## 插件类型
+
+Modern.js 中内置了三种不同的框架插件：
+
+- `CLI 插件`，适用于本地开发、编译构建阶段，可以在命令行和编译阶段扩展各种能力。
+- `Server 插件`，适用于服务端。
+- `Runtime 插件`，适用于前端运行时。
+
+目前 Modern.js 开放了自定义 CLI 插件的能力，Server 插件和 Runtime 插件会在后续开放。
+
+## 插件执行顺序
+
+默认情况下，自定义插件会按照 `plugins` 数组的顺序依次执行，Modern.js 内置插件的执行时机早于自定义插件。
+
+当插件内部使用了控制顺序的相关字段，比如 `pre`、`post` 时，会基于声明的字段对执行顺序进行调整，详见 [插件之间的关系](/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/intro.mdx

@@ -0,0 +1,120 @@
+---
+sidebar_label: 总览
+sidebar_position: 1
+---
+
+# 总览
+
+此节将介绍 Runtime 插件的配置。
+
+## 配置方式
+
+### runtime
+
+- **类型：** `Object`
+
+runtime 配置方式如下：
+
+#### 基本用法
+
+在 `modern.config.ts` 中配置
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  runtime: {
+    state: true,
+    router: true,
+  },
+});
+```
+
+#### 运行时配置
+
+通过 [`defineConfig`](/apis/app/runtime/app/define-config) API 配置：
+
+:::info
+当 runtime 配置中存在函数时，只能使用该方式进行配置。
+
+:::
+
+import { Tabs, Tab as TabItem } from "@theme";
+
+<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';
+
+const App = () => {
+  /** */
+};
+
+defineConfig(App, {
+  router: {
+    supportHtml5History: false,
+  },
+});
+
+export default App;
+```
+
+  </TabItem>
+</Tabs>
+
+:::info
+使用运行时配置，可以解决 Runtime 插件配置需要在运行时才能获取到具体内容问题。
+
+Runtime 插件运行时配置和直接在 `modern.config.ts` 中的配置默认会进行合并，且运行时配置优先级更高。
+
+:::
+
+:::warning
+defineConfig 中只能定义 Runtime 插件的具体配置内容，确认是否开启插件还需要通过 `package.json` 中的 `modernConfig` 或者 `modern.config.ts` 中的配置决定。
+
+:::
+
+### runtimeByEntries
+
+- **类型：** `Object`
+- **默认值：**无
+
+#### 说明
+
+按入口添加 runtime 配置，选项属性同 runtime 一致，指定值会和 runtime 属性内容做替换合并操作。
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  runtime: {
+    state: false,
+  },
+  runtimeByEntries: {
+    entry1: {
+      state: true, // { state: true }
+    },
+    entry2: {
+      // { state: false, router: true }
+      router: true,
+    },
+  },
+});
+```

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

@@ -0,0 +1,42 @@
+---
+sidebar_label: masterApp
+---
+
+# runtime.masterApp
+
+- **类型：** `Object`
+
+:::info
+需要先通过 `pnpm run new` 启用「微前端」 功能。
+
+:::
+
+## 示例
+
+import EnableMicroFrontend from "@site-docs/components/enable-micro-frontend";
+import MasterManifestAppConfig from "@site-docs/components/micro-master-manifest-config";
+
+<EnableMicroFrontend />
+<MasterManifestAppConfig />
+
+### apps
+
+当 `apps` 为对象类型的时候，表示子应用模块的信息 `Array<AppInfo>`
+
+```ts
+interface AppInfo {
+  name: string;
+  entry: string;
+  activeWhen?: string | ()=> boolean;
+}
+```
+
+- name: 子应用的名称。
+- entry: 子应用的入口。
+- activeWhen?: 子应用激活路径。
+
+### 其他配置项
+
+在 `masterApp` 配置下，开发者可以透传 Garfish 的配置项。
+
+所有支持的配置项[点此查看](https://garfishjs.org/api/run/#%E5%8F%82%E6%95%B0)。

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

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

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

@@ -0,0 +1,54 @@
+---
+sidebar_label: state
+---
+
+# runtime.state
+
+- **类型：** `boolean | object`
+- **默认值：** `false`
+
+开启 `state` 后就可以使用 [Model](/guides/topic-detail/model/quick-start) 来做状态管理。
+
+具体配置项如下：
+
+## models
+
+- **类型：** `Array<Model>`
+- **默认值：** `[]`
+
+注册提前挂载的 model 对象，这些 model 会在 Reduck store 创建完成后立即执行挂载。一般使用无需提前挂载。
+
+## initialState
+
+- **类型：** `Object`
+- **默认值：** `{}`
+
+用于设置全局 store 的初始状态。一般用于 SSR 在 hydration 阶段初始化数据。
+
+## 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/check-syntax.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: checkSyntax
+---
+
+# security.checkSyntax
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [security.checkSyntax](https://modernjs.dev/builder/api/config-security.html#security-checksyntax)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/security/checkSyntax.md'
+
+<Main />

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

@@ -0,0 +1,13 @@
+---
+sidebar_label: sri
+---
+
+# security.sri
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [security.sri](https://modernjs.dev/builder/api/config-security.html#security-sri)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/security/sri.md'
+
+<Main />