@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.0

package/docs/zh/configure/app/server/ssr-by-entries.mdx

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

package/docs/zh/configure/app/server/ssr.mdx

@@ -0,0 +1,85 @@
+---
+title: ssr
+---
+
+# server.ssr
+
+- **类型：** `boolean` | `Object`
+- **默认值：** `false`
+
+SSR 开关以及相关设置。
+
+### Boolean 类型
+
+当值类型为 `boolean` 时，表示是否开启 SSR 部署模式，默认 `false` 不开启。
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    ssr: true,
+  },
+});
+```
+
+### Object 类型
+
+当值类型为 `Object` 时，可以配置如下属性：
+
+| 属性              | 类型                                                               | 默认值                                   | 描述                                                                     |
+| ---------------- | ------------------------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------- |
+| mode             | `string`                                  | `stream`          | 默认为使用流式渲染。配置为 `string` 使用 `renderToString` 渲染       |
+| forceCSR         | `boolean`                                 | `false`           | 默认关闭强制 CSR 渲染。配置为 `true` 后，在页面访问时添加 `?csr=true` 或添加请求头 `x-modern-ssr-fallback` 即可强制 CSR |
+| unsafeHeaders    | `string[]`                                | `[]`              | 为了安全考虑，Modern.js 不会往 SSR_DATA 添加过多的内容。开发者可以通过该配置，对需要注入的 headers 进行配置       |
+| loaderFailureMode| `clientRender \| errorBoundary`           | `errorBoundary` | 当 [data loader](/guides/basic-features/data/data-fetch.html#data-loader推荐) 中出错时，默认会渲染路由 [`Error`](/guides/basic-features/routes/routes#错误处理) 组件，配置为 `'clientRender'` 时，有一个 data loader 抛错，就降级到客户端渲染，可以与 [Client Loader](/guides/basic-features/data/data-fetch.html#client-loader) 配合使用 |
+| moduleFederationAppSSR | `boolean`                           | `false`           | 启用应用级 Module Federation SSR 契约握手。使用应用级 MF SSR 时需在 host 与 remote 两侧同时开启 |
+
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    ssr: {
+      forceCSR: true,
+      mode: 'stream',
+      unsafeHeaders: ['User-Agent'],
+      moduleFederationAppSSR: true,
+    },
+  },
+});
+```
+
+### 主动降级
+
+在生产环境，有时需要将 SSR 项目主动降级到 CSR，例如：
+
+1. SSR 出现故障，需要降级到 CSR，保证产品可用性。
+
+2. SSR 正常数据获取时页面渲染正常，但出错降级后渲染失败，需要进行调试。
+
+3. SSR 服务压力过大，需要部分流量直接降级为 CSR，避免服务宕机。
+
+在项目中配置 `server.ssr.forceCSR` 为 `true` 后，我们可以通过请求的查询字符串、context，或是请求头来控制这一行为。
+
+例如在自定义 Web Server 的中间件中，检测到流量大于某一阈值时，主动降级：
+
+```ts title="server/modern.server.ts"
+import {
+  defineServerConfig,
+  type MiddlewareHandler,
+} from '@modern-js/server-runtime';
+
+export const handler: MiddlewareHandler = async (c, next) => {
+  if (condition) {
+    c.set('forceCSR', '1');
+  }
+  await next();
+};
+
+export default defineServerConfig({
+  middlewares: [
+    {
+      name: 'request-middleware',
+      handler,
+    },
+  ],
+});
+```

package/docs/zh/configure/app/server/tsconfig-path.mdx

@@ -0,0 +1,63 @@
+---
+title: tsconfigPath
+---
+
+# server.tsconfigPath
+
+- **类型：** `string`
+- **默认值：** `<appDirectory>/tsconfig.json`
+
+指定服务端 TypeScript 相关流程使用的 tsconfig 文件。
+
+该配置会影响：
+
+- BFF / API 编译（`@modern-js/plugin-bff`）
+- 自定义 Server 编译（`server/` 目录下的 `*.ts` 文件）
+- 运行时 Node 原生 TypeScript 注册（如 SSR、`modern.config.ts`、`config/` 目录下的 `.ts` 文件）
+
+未配置时，默认使用 `<appDirectory>/tsconfig.json`。
+
+## 使用场景
+
+当前端和服务端需要不同的 TypeScript 配置时，可以通过该选项为服务端单独指定 tsconfig。
+
+例如前端使用 `moduleResolution: "Bundler"`，服务端需要使用 `moduleResolution: "NodeNext"` 来适配 conditional exports 或 subpath exports 的类型解析。
+
+## 配置示例
+
+下面以 `tsconfig.server.json` 为例，你也可以根据项目情况使用其他文件名。
+
+新增 `<appDirectory>/tsconfig.server.json`：
+
+```jsonc title="tsconfig.server.json"
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "target": "ES2022",
+    "lib": ["ESNext"],
+    "types": ["node"],
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  },
+  "include": ["api", "shared", "server", "config", "modern.config.ts"]
+}
+```
+
+在 `modern.config.ts` 中指定该文件：
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    tsconfigPath: './tsconfig.server.json',
+  },
+});
+```
+
+## 注意事项
+
+- `tsconfigPath` 相对 `appDirectory` 解析，也支持绝对路径。
+- 建议通过 `extends` 继承根 tsconfig 中的 `paths` 等公共配置，避免重复维护。
+- 如果配置的文件不存在，运行时 TypeScript 设置 会在启动时抛出错误。

package/docs/zh/configure/app/source/alias-strategy.mdx

@@ -0,0 +1,18 @@
+---
+title: aliasStrategy
+---
+
+# source.aliasStrategy
+
+:::warning 废弃警告
+`source.aliasStrategy` 已废弃，请使用 [resolve.aliasStrategy](/configure/app/resolve/alias-strategy) 代替。
+:::
+
+- **类型：** `'prefer-tsconfig' | 'prefer-alias'`
+- **默认值：** `'prefer-tsconfig'`
+
+`source.aliasStrategy` 用于控制 `tsconfig.json` 中的 `paths` 选项与打包工具的 `alias` 选项的优先级。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="source.aliasStrategy" />

package/docs/zh/configure/app/source/alias.mdx

@@ -0,0 +1,27 @@
+---
+title: alias
+---
+
+# source.alias
+
+:::warning 废弃警告
+`source.alias` 已废弃，请使用 [resolve.alias](/configure/app/resolve/alias) 代替。
+:::
+
+- **类型:**
+
+```ts
+type Alias = Record<string, string | false | (string | false)[]> | Function;
+```
+
+- **默认值:** `undefined`
+
+设置文件引用的别名，对应 Rspack 的 [resolve.alias](https://rspack.rs/config/resolve#resolvealias) 配置。
+
+:::tip
+对于 TypeScript 项目，你只需要在 `tsconfig.json` 中配置 [compilerOptions.paths](https://www.typescriptlang.org/tsconfig#paths) 即可，Rsbuild 会自动识别它，不需要额外配置 `source.alias` 字段，详见 [「路径别名」](https://modernjs.dev/guides/basic-features/alias.html)。
+:::
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="source.alias" />

package/docs/zh/configure/app/source/config-dir.mdx

@@ -0,0 +1,24 @@
+---
+title: configDir
+---
+
+# source.configDir
+
+- **类型：** `string`
+- **默认值：** `'./config'`
+
+Modern.js 支持在 `./config` 文件夹下放置一些文件自定义 HTML 模板、图标、静态资源等，具体可参考[文件约定](/apis/app/hooks/config/html)。
+
+通过该选项可以自定义配置文件的目录。
+
+例如，将资源文件目录调整为 `resources` 目录：
+
+```js title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    configDir: './resources',
+  },
+});
+```

package/docs/zh/configure/app/source/decorators.mdx

@@ -0,0 +1,27 @@
+---
+title: decorators
+---
+
+# source.decorators
+
+- **类型：**
+
+```ts
+type Decorators = {
+  version?: 'legacy' | '2022-03';
+};
+```
+
+- **默认值：**
+
+```js
+const defaultDecorators = {
+  version: 'legacy';
+};
+```
+
+:::warning
+该配置项的使用方式与 Rsbuild 一致，但默认值不同。详细信息请参考 [Rsbuild - source.decorators](https://v2.rsbuild.rs/zh/config/source/decorators)。
+:::
+
+我们发现大部分的项目仍使用 `legacy` 版本的装饰器语法，因此默认值为 `legacy`。

package/docs/zh/configure/app/source/define.mdx

@@ -0,0 +1,20 @@
+---
+title: define
+---
+
+# source.define
+
+- **类型：** `Record<string, unknown>`
+- **默认值：**
+
+```ts
+const defaultDefine = {
+  'process.env.MODERN_TARGET': '"browser"',
+};
+```
+
+构建时将代码中的变量替换成其它值或者表达式，可以用于在代码逻辑中区分开发环境与生产环境等场景。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="source.define" />

package/docs/zh/configure/app/source/disable-default-entries.mdx

@@ -0,0 +1,32 @@
+---
+title: disableDefaultEntries
+---
+
+# source.disableDefaultEntries
+
+- **类型：** `boolean`
+- **默认值：** `false`
+
+用于关闭基于目录结构来自动识别页面入口的功能。
+
+:::info
+默认情况下，Modern.js 会基于目录约定来自动确定页面的入口，具体可参考[入口](/guides/concept/entries)。
+
+:::
+
+设置如下，即可关闭默认的行为：
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    disableDefaultEntries: true,
+  },
+});
+```
+
+关闭默认行为后，你需要使用 [`source.entries`](/configure/app/source/entries) 配置自定义的入口。
+
+:::warning
+我们推荐使用 Modern.js 提供的目录规范来组织代码，从而更好地使用框架功能，避免一些冗余的配置。
+
+:::

package/docs/zh/configure/app/source/enable-async-entry.mdx

@@ -0,0 +1,54 @@
+---
+title: enableAsyncEntry
+---
+
+# source.enableAsyncEntry
+
+- **类型：** `boolean`
+- **默认值：** `false`
+
+该选项用于 Rspack 模块联邦（Module Federation）场景。
+
+开启此选项后，Modern.js 会通过 dynamic import 来包裹自动生成的入口文件（Asynchronous Boundaries），使页面代码可以消费模块联邦生成的远程模块。
+
+## 背景知识
+
+import ModuleFederation from '@site-docs/components/module-federation.mdx';
+
+<ModuleFederation />
+
+## 示例
+
+首先，在配置文件中开启此选项：
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    enableAsyncEntry: true,
+  },
+});
+```
+
+然后执行 `dev` 或 `build` 命令，可以看到 Modern.js 自动生成的文件变为以下结构：
+
+```bash
+node_modules
+  └─ .modern-js
+     └─ main
+        ├─ bootstrap.jsx  # 异步入口文件（asynchronous boundary）
+        ├─ index.js      # 真正的入口代码
+        └─ index.html
+```
+
+其中 `bootstrap.js` 的内容如下：
+
+```js
+import('./index.jsx');
+```
+
+此时，就可以在当前页面中消费任意的远程模块了。
+
+:::info
+Modern.js 未对 ModuleFederationPlugin 进行封装，请通过 [tools.bundlerChain](/configure/app/tools/bundler-chain) 自行配置 ModuleFederationPlugin。
+
+:::

package/docs/zh/configure/app/source/enable-async-pre-entry.mdx

@@ -0,0 +1,77 @@
+---
+title: enableAsyncPreEntry
+---
+
+# source.enableAsyncPreEntry
+
+- **类型：** `boolean`
+- **默认值：** `false`
+
+开启后，Modern.js 会在自动生成的入口文件（`index.jsx`）最上方依次插入 `source.preEntry` 中配置的模块 import。
+
+该配置仅在 `source.enableAsyncEntry` 开启时生效；如果未开启异步入口，则不会启用该行为（并保持 `source.preEntry` 原有的构建器注入逻辑不受影响）。
+
+该配置主要用于配合 `source.enableAsyncEntry` 使用：当启用异步入口时，最终的构建 entry 会变为 `bootstrap.jsx`，这会导致构建器侧的 `source.preEntry` 不一定能注入到真正的入口代码中。开启 `source.enableAsyncPreEntry` 后，`preEntry` 会注入到 `index.jsx`（真正的入口代码）顶部，从而保证在异步入口场景下也能生效。
+
+同时，当 `source.enableAsyncPreEntry` 开启时，Modern.js 不会将 `source.preEntry` 传递给构建器配置，避免重复注入或注入到不期望的 entry 中。
+
+## 示例
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    enableAsyncEntry: true,
+    enableAsyncPreEntry: true,
+    preEntry: ['./src/pre-a.ts', './src/pre-b.ts'],
+  },
+});
+```
+
+## 编译效果
+
+在开启 `source.enableAsyncEntry` 后，Modern.js 会为每个入口生成一个异步边界文件 `bootstrap.jsx`，并由它去动态加载真正的入口代码 `index.jsx`。
+
+当同时开启 `source.enableAsyncPreEntry` 时，Modern.js 会把 `source.preEntry` 以 `import` 的形式注入到 **`index.jsx` 的最顶部**（而不是注入到 `bootstrap.jsx`），保证异步入口场景下 `preEntry` 一定会在入口代码之前执行。
+
+### 生成文件结构
+
+以单入口 `main` 为例，生成的文件结构大致如下（位于 `node_modules/.modern-js/main/`）：
+
+```bash
+node_modules
+  └─ .modern-js
+     └─ main
+        ├─ bootstrap.jsx        # 最终用于构建的 entry（异步边界）
+        ├─ index.jsx            # 真正的入口代码（会被注入 preEntry import）
+        ├─ register.js
+        ├─ runtime-register.js
+        └─ runtime-global-context.js
+```
+
+### bootstrap.jsx
+
+`bootstrap.jsx` 的核心逻辑是通过 dynamic import 加载 `index.jsx`：
+
+```js title="node_modules/.modern-js/main/bootstrap.jsx"
+import(/* webpackChunkName: "async-main" */ './index');
+```
+
+### index.jsx（会注入 preEntry）
+
+开启 `source.enableAsyncPreEntry` 后，`index.jsx` 文件的最上方会被注入 `source.preEntry` 对应的 import，随后才是 Modern.js 生成的入口逻辑，例如：
+
+```js title="node_modules/.modern-js/main/index.jsx"
+import '@_modern_js_src/pre-a.ts';
+import '@_modern_js_src/pre-b.ts';
+
+import '@modern-js/runtime/registry/main';
+// ...后续为 Modern.js 自动生成的入口逻辑
+```
+
+其中 `@_modern_js_src` 是 Modern.js 内部用于指向项目 `src` 目录的别名（实际值会随项目 metaName 等信息变化）。
+
+### 与 builder 的关系
+
+当 `source.enableAsyncEntry` 与 `source.enableAsyncPreEntry` 同时开启时，Modern.js **不会再把 `source.preEntry` 传递给构建器配置**，避免构建器重复注入或注入到不期望的 entry 中。

package/docs/zh/configure/app/source/entries-dir.mdx

@@ -0,0 +1,39 @@
+---
+title: entriesDir
+---
+
+# source.entriesDir
+
+- **类型：** `string`
+- **默认值：** `'./src'`
+
+Modern.js 默认会扫描 `src` 目录来识别页面入口，你可以通过该选项自定义页面入口的识别目录。
+
+例如，当配置与目录结构如下时：
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    entriesDir: './src/pages',
+  },
+});
+```
+
+```bash title="项目目录结构"
+.
+└── src
+    └── pages
+        ├── a
+        │   └── App.tsx
+        └── b
+            └── App.tsx
+```
+
+Modern.js 会扫描 `./src/pages` 目录，自动生成构建入口 `a` 和入口 `b`，结果如下：
+
+```js
+const entry = {
+  a: './src/pages/a/App.tsx',
+  b: './src/pages/b/App.tsx',
+};
+```

package/docs/zh/configure/app/source/entries.mdx

@@ -0,0 +1,185 @@
+---
+title: entries
+---
+
+# source.entries
+
+- **类型：**
+
+```ts
+type Entries = Record<
+  string,
+  | string
+  | {
+      entry: string;
+      disableMount?: boolean;
+    }
+>;
+```
+
+- **默认值：** 根据当前项目的目录结构计算出的入口对象。
+
+用于配置自定义页面入口。
+
+:::tip 何时使用
+对于大部分场景，Modern.js 根据目录结构自动生成的入口已经可以满足需求，具体可参考[入口](/guides/concept/entries)。
+
+如果你需要自定义页面入口时，可以通过该选项进行设置。
+
+:::
+
+## String 类型
+
+当 `entries` 对象的 value 为 `string` 类型时，表示入口模块的文件路径:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    entries: {
+      // 指定一个名称为 'my-entry' 的新入口
+      'my-entry': './src/home/test/index.ts',
+    },
+    // 禁用默认入口扫描
+    disableDefaultEntries: true,
+  },
+});
+```
+
+默认情况下，配置的入口等价于 `App.tsx`，即指定的入口文件**只需要导出应用的根组件**。
+
+例如以下目录结构：
+
+```bash
+.
+├── src
+│   └── entry
+│       ├── chat.tsx
+│       └── home.tsx
+└── package.json
+```
+
+上述目录不符合 Modern.js 的目录结构约定，因此，Modern.js 在分析目录结构时，不会得到任何默认入口。
+
+在不想改变目录结构的情况下（如项目迁移），可以通过 `source.entries` 自定义入口：
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    entries: {
+      home: './src/entry/home.tsx',
+      chat: './src/entry/chat.tsx',
+    },
+    // 禁用默认入口扫描
+    disableDefaultEntries: true,
+  },
+});
+```
+
+## Object 类型
+
+当值为 `Object` 时，可配置如下属性：
+
+- `entry`：`string`，入口文件路径。
+- `disableMount`：`boolean = false`，关闭 Modern.js 自动生成入口代码的行为。
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    entries: {
+      'my-entry': {
+        // 入口文件路径
+        entry: './src/my-page/index.tsx',
+        disableMount: true,
+      },
+    },
+    // 禁用默认入口扫描
+    disableDefaultEntries: true,
+  },
+});
+```
+
+### 禁用入口文件生成
+
+默认情况下，配置的入口等价于 `App.tsx`，Modern.js 会自动生成一个入口文件来引用你配置的入口。
+
+如果你希望禁用 Modern.js 自动生成入口文件的逻辑，可以将 `disableMount` 属性设置为 `true`。
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    entries: {
+      'my-entry': {
+        entry: './src/my-page/index.tsx',
+        disableMount: true,
+      },
+    },
+    // 禁用默认入口扫描
+    disableDefaultEntries: true,
+  },
+});
+```
+
+### 约定式路由
+
+如果你需要为某个自定义入口启用约定式路由，可以将 `entry` 设置为目录路径：
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    entries: {
+      // 启用约定式路由
+      entry_spa: {
+        // 约定式路由的入口路径必须设置为目录
+        entry: './src/about',
+      },
+    },
+    // 禁用默认入口扫描
+    disableDefaultEntries: true,
+  },
+});
+```
+
+## 入口合并规则
+
+在设置 `source.entries` 后，如果没有设置 `disableDefaultEntries: true`，Modern.js 会将自定义入口与分析目录结构得到的入口合并。
+
+合并规则为：
+
+- 比较自定义入口设置的入口路径和默认入口路径，当入口路径一致时，自定义入口会覆盖默认入口。
+
+例如以下目录结构:
+
+```bash
+.
+├── src
+│   ├── chat
+│   │   └── App.tsx
+│   └── home
+│       └── index.ts
+└── package.json
+```
+
+Modern.js 会分析 `src/` 目录，得到默认入口 `chat` 和 `home`。当用户在 `modern.config.ts` 文件中配置如下时：
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    entries: {
+      index: './src/home/index.ts',
+    },
+  },
+};
+```
+
+可以看到自定义入口 `index` 的路径和默认入口 `home` 的路径一致，在合并的过程中，`index` 会覆盖掉 `home`，最终入口如下：
+
+- `chat -> ./src/chat/App.tsx`
+- `index -> ./src/home/index.ts`