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

package/docs/zh/configure/_meta.json

@@ -0,0 +1,78 @@
+[
+  "app/usage",
+  {
+    "type": "dir",
+    "name": "app/dev",
+    "label": "dev",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "app/bff",
+    "label": "bff",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "app/html",
+    "label": "html",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "app/tools",
+    "label": "tools",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "app/source",
+    "label": "source",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "app/resolve",
+    "label": "resolve",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "app/server",
+    "label": "server",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "app/output",
+    "label": "output",
+    "collapsed": true
+  },
+  "app/plugins",
+  {
+    "type": "dir",
+    "name": "app/security",
+    "label": "security",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "app/runtime",
+    "label": "runtime",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "app/performance",
+    "label": "performance",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "app/experiments",
+    "label": "experiments",
+    "collapsed": true
+  },
+  "app/builder-plugins",
+  "app/split-chunks"
+]

package/docs/zh/configure/app/bff/cross-project.mdx

@@ -0,0 +1,24 @@
+---
+title: crossProject
+---
+
+# bff.crossProject
+
+- **类型：** `boolean`
+- **默认值：** `false`
+
+import EnableBFFCaution from "@site-docs/components/enable-bff-caution";
+
+<EnableBFFCaution />
+
+该配置用于启用 BFF 跨项目调用功能。启用后，可以将当前项目作为 BFF 生产端，生成可被其他项目直接调用的 SDK。
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    crossProject: true,
+  },
+});
+```
+
+有关 BFF 跨项目调用的详细配置和使用方法，请参考 [BFF 跨项目调用指南](/guides/advanced-features/bff/cross-project.html)。

package/docs/zh/configure/app/bff/effect.mdx

@@ -0,0 +1,152 @@
+---
+title: effect
+---
+
+# bff.effect
+
+- **类型：**
+
+```ts
+type BffEffectUserConfig = {
+  entry?: string;
+  openapi?: boolean | { path?: string };
+  dataPlatform?: {
+    enabled?: boolean;
+    requireEnvelope?: boolean;
+    envelopeHeader?: string;
+    expectedNamespace?: string;
+    validateOrigin?: boolean;
+    requireTraceContext?: boolean;
+    selection?: {
+      maxDepth?: number;
+      maxFields?: number;
+      allowedLeafPaths?: string[];
+    };
+    batch?: {
+      enabled?: boolean;
+      endpoint?: `/${string}`;
+      maxBatchSize?: number;
+      maxBatchBytes?: number;
+      flushIntervalMs?: number;
+      maxConcurrency?: number;
+      requestTimeoutMs?: number;
+      allowedMethods?: string[];
+    };
+  };
+};
+```
+
+- **默认值：** `{}`
+
+import EnableBFFCaution from "@site-docs/components/enable-bff-caution";
+
+<EnableBFFCaution />
+
+仅当 `bff.runtimeFramework` 设置为 `'effect'` 时，`bff.effect` 才会生效。
+
+对于 Effect v4，TypeScript 需要使用支持 `exports` 映射的模块解析方式。
+
+```json title="tsconfig.json"
+{
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "Bundler"
+  }
+}
+```
+
+## bff.effect.entry
+
+- **类型：** `string`
+- **默认值：** `<apiDirectory>/effect/index`
+
+用于指定 Effect HttpApi 运行时入口模块。
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    runtimeFramework: 'effect',
+    effect: {
+      entry: './api/effect/index',
+    },
+  },
+});
+```
+
+## bff.effect.openapi
+
+- **类型：** `boolean | { path?: string }`
+- **默认值：** `false`
+
+为 Effect HttpApi 运行时开启 OpenAPI 接口描述生成。
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    runtimeFramework: 'effect',
+    effect: {
+      openapi: {
+        path: '/openapi.json',
+      },
+    },
+  },
+});
+```
+
+## bff.effect.dataPlatform
+
+- **类型：**
+
+```ts
+{
+  enabled?: boolean;
+  requireEnvelope?: boolean;
+  envelopeHeader?: string;
+  expectedNamespace?: string;
+  validateOrigin?: boolean;
+  requireTraceContext?: boolean;
+  selection?: {
+    maxDepth?: number;
+    maxFields?: number;
+    allowedLeafPaths?: string[];
+  };
+  batch?: {
+    enabled?: boolean;
+    endpoint?: `/${string}`;
+    maxBatchSize?: number;
+    maxBatchBytes?: number;
+    flushIntervalMs?: number;
+    maxConcurrency?: number;
+    requestTimeoutMs?: number;
+    allowedMethods?: string[];
+  };
+}
+```
+
+- **默认值：** `{ enabled: true }`
+
+用于配置 Effect 运行时的数据请求信封（envelope）校验策略。
+
+生成的 Effect 客户端会将批处理请求发送到 `${bff.prefix}${batch.endpoint}`（例如 `/bff-api/_data/batch`）。
+
+当 `validateOrigin` 开启时，运行时会优先将 envelope 中的 origin 与请求 `Origin` 头比对；若请求无 `Origin`，则回退到请求 URL 的 origin。
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    runtimeFramework: 'effect',
+    effect: {
+      dataPlatform: {
+        requireEnvelope: true,
+        expectedNamespace: 'my-app',
+        selection: {
+          maxDepth: 6,
+          maxFields: 200,
+        },
+      },
+    },
+  },
+});
+```
+
+`batch.flushIntervalMs` 用于控制生成的 Effect 客户端微批处理窗口；`maxConcurrency` 与 `requestTimeoutMs` 由服务端批处理网关用于内部请求分发。

package/docs/zh/configure/app/bff/prefix.mdx

@@ -0,0 +1,33 @@
+---
+title: prefix
+---
+
+# bff.prefix
+
+- **类型：** `string`
+- **默认值：** `/api`
+
+import EnableBFFCaution from "@site-docs/components/enable-bff-caution";
+
+<EnableBFFCaution />
+
+默认情况下，BFF API 目录下的路由访问前缀是 `/api`, 如下目录结构：
+
+```bash
+api
+└── hello.ts
+```
+
+`api/hello.ts` 访问时对应的路由为 `localhost:8080/api/hello`。
+
+该配置选项可以修改默认的路由前缀：
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    prefix: '/api-demo',
+  },
+});
+```
+
+对应的 `api/hello.ts` 访问路由为 `localhost:8080/api-demo/hello`。

package/docs/zh/configure/app/bff/runtime-framework.mdx

@@ -0,0 +1,28 @@
+---
+title: runtimeFramework
+---
+
+# bff.runtimeFramework
+
+- **类型：** `'hono' | 'effect'`
+- **默认值：** `'effect'`
+
+import EnableBFFCaution from "@site-docs/components/enable-bff-caution";
+
+<EnableBFFCaution />
+
+用于控制 Modern.js BFF 路由使用的运行时框架。
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    runtimeFramework: 'effect',
+  },
+});
+```
+
+- 设置为 `'effect'` 时，仅从 `api/effect/index` 运行 BFF（Effect HttpApi 运行时）。
+- 设置为 `'hono'` 时，仅从 `api/lambda/**` 的文件约定处理函数运行 BFF。
+
+两种运行时之间没有隐式回退，应用需要显式选择其一。
+如果需要优先使用 Effect 分支的公开 UltraModern 预设，请在应用中显式设置，或使用 create 模板提供的 Effect 脚手架路径。

package/docs/zh/configure/app/builder-plugins.mdx

@@ -0,0 +1,72 @@
+---
+sidebar_position: 21
+---
+
+# builderPlugins
+
+- **类型：** `RsbuildPlugin[]`
+- **默认值：** `[]`
+
+用于配置 Rsbuild 构建插件。
+
+Rsbuild 是 Modern.js 底层的构建工具，请阅读 [构建能力](/guides/concept/builder) 了解相关背景。
+
+如果你想了解 Rsbuild 插件的编写方式，可以参考 [Rsbuild - 插件系统](https://v2.rsbuild.rs/zh/plugins/dev/index)。
+
+## 注意事项
+
+该选项**用于配置 Rsbuild 构建插件**，如果你需要配置其他类型的插件，请选择对应的配置方式：
+
+- 配置 Modern.js 框架插件，请使用 [plugins](/configure/app/plugins) 配置项。
+- 配置 Rspack 插件，请使用 [tools.bundlerChain](/configure/app/tools/bundler-chain) 配置项。
+
+## 何时使用
+
+大部分场景下，我们推荐你使用 Modern.js 框架插件，框架插件可以通过 [plugins](/configure/app/plugins) 字段进行注册。因为框架插件提供的 API 更丰富、能力更强，而 Rsbuild 插件提供的 API 只能用于构建场景。
+
+当你需要引用一些现有的 Rsbuild 插件（并且在 Modern.js 中没有相关能力），或是在不同的框架之间复用 Rsbuild 插件时，你可以使用 `builderPlugins` 字段进行注册。
+
+## 示例
+
+下面是 Rsbuild 插件的使用示例。
+
+### 使用 npm 上的插件
+
+使用 npm 上的插件，需要通过包管理器安装插件，并通过 import 引入。
+
+```ts title="modern.config.ts"
+import { myRsbuildPlugin } from 'my-rsbuild-plugin';
+
+export default defineConfig({
+  builderPlugins: [myRsbuildPlugin()],
+});
+```
+
+### 使用本地插件
+
+使用本地代码仓库中的插件，直接通过相对路径 import 引入即可。
+
+```ts title="modern.config.ts"
+import { myRsbuildPlugin } from './plugin/myRsbuildPlugin';
+
+export default defineConfig({
+  builderPlugins: [myRsbuildPlugin()],
+});
+```
+
+### 插件配置项
+
+如果插件提供了一些自定义的配置项，可以通过插件函数的参数传入配置。
+
+```ts title="modern.config.ts"
+import { myRsbuildPlugin } from 'my-rsbuild-plugin';
+
+export default defineConfig({
+  builderPlugins: [
+    myRsbuildPlugin({
+      foo: 1,
+      bar: 2,
+    }),
+  ],
+});
+```

package/docs/zh/configure/app/dev/asset-prefix.mdx

@@ -0,0 +1,18 @@
+---
+title: assetPrefix
+---
+
+# dev.assetPrefix
+
+- **类型：** `boolean | string | 'auto'`
+- **默认值：** `'/'`
+
+此配置项用于设置 **开发模式** 下的静态资源 URL 前缀。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="dev.assetPrefix" />
+
+:::warning
+请注意，该配置项仅适用于开发模式。在生产模式下，请使用 [output.assetPrefix](/configure/app/output/asset-prefix) 配置项进行设置。
+:::

package/docs/zh/configure/app/dev/before-start-url.mdx

@@ -0,0 +1,21 @@
+---
+title: beforeStartUrl
+---
+
+# dev.beforeStartUrl
+
+- **类型：** `() => Promise<void> | void`
+- **默认值：** `undefined`
+
+`dev.beforeStartUrl` 用于在打开 `startUrl` 前执行一段回调函数，该配置项需要与 [`dev.startUrl`](/configure/app/dev/start-url) 一同使用。
+
+```js
+export default {
+  dev: {
+    startUrl: true,
+    beforeStartUrl: async () => {
+      await doSomeThing();
+    },
+  },
+};
+```

package/docs/zh/configure/app/dev/client.mdx

@@ -0,0 +1,45 @@
+---
+title: client
+---
+
+# dev.client
+
+- **类型：**
+
+```ts
+type Client = {
+  // WebSocket 请求的协议名称
+  protocol?: 'ws' | 'wss';
+  // WebSocket 请求的路径
+  path?: string;
+  // WebSocket 请求的端口号
+  port?: string | number;
+  // WebSocket 请求的 host
+  host?: string;
+  // WebSocket 请求断开后的最大重连次数
+  reconnect?: number;
+  // 当出现编译错误时，是否在浏览器中显示 error overlay
+  overlay?: boolean;
+};
+```
+
+- **默认值：**
+
+```js
+const defaultConfig = {
+  path: '/webpack-hmr',
+  port: '<port>',
+  // 默认为 "location.hostname"
+  host: '',
+  // 默认为 "location.protocol === 'https:' ? 'wss' : 'ws'""
+  protocol: undefined,
+  reconnect: 100,
+  overlay: false,
+};
+```
+
+配置 Modern.js 在开发过程中注入的 client 代码，可以用于设置热更新对应的 WebSocket URL。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="dev.client" />

package/docs/zh/configure/app/dev/hmr.mdx

@@ -0,0 +1,14 @@
+---
+title: hmr
+---
+
+# dev.hmr
+
+- **类型：** `boolean`
+- **默认值：** `true`
+
+是否开启 Hot Module Replacement 热更新能力。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="dev.hmr" />

package/docs/zh/configure/app/dev/host.mdx

@@ -0,0 +1,22 @@
+---
+title: host
+---
+
+# dev.host
+
+- **类型：** `string`
+- **默认值：** `0.0.0.0`
+
+指定 dev server 启动时监听的 host。
+
+默认情况下，dev server 会监听 `0.0.0.0`，这代表监听所有的网络接口，包括 `localhost` 和公网地址。
+
+如果你希望 dev server 只监听 `localhost`，可以设置为：
+
+```ts
+export default {
+  dev: {
+    host: 'localhost',
+  },
+};
+```

package/docs/zh/configure/app/dev/https.mdx

@@ -0,0 +1,82 @@
+---
+title: https
+---
+
+# dev.https
+
+- **类型：** `boolean | { key: string; cert: string }`
+- **默认值：** `false`
+
+配置该选项后，可以开启 Dev Server 对 HTTPS 的支持，同时会禁用 HTTP 服务器。
+
+开启前：
+
+```bash
+  > Local:    http://localhost:8080/
+  > Network:  http://192.168.0.1:8080/
+```
+
+开启后：
+
+```bash
+  > Local:    https://localhost:8080/
+  > Network:  https://192.168.0.1:8080/
+```
+
+#### 自动生成证书
+
+你可以直接将 `https` 设置为 `true`，Modern.js 会基于 [devcert](https://github.com/davewasmer/devcert) 来自动生成 Dev Server 所需的 HTTPS 证书。
+
+使用这种方式时，你需要在当前项目中手动安装 [devcert](https://github.com/davewasmer/devcert) 依赖：
+
+```bash
+# npm
+npm install devcert@1.2.2 -D
+
+# yarn
+yarn add devcert@1.2.2 -D
+
+# pnpm
+pnpm add devcert@1.2.2 -D
+```
+
+然后配置 `dev.https` 为 `true` 即可：
+
+```ts
+export default {
+  dev: {
+    https: true,
+  },
+};
+```
+
+该方式有一定局限性，由于 devcert 目前不支持 IP addresses，因此访问 Network 域名时，会遇到「您的连接不是私密连接」的问题。
+
+此问题的解决方法为：点击 Chrome 浏览器问题页面的「高级」->「继续前往 192.168.0.1（不安全）」。
+
+:::tip
+https 代理自动安装证书需要获取 root 权限, 请根据提示输入密码即可。 **密码仅在信任证书时使用，不会泄漏或者用于其他环节**。
+:::
+
+#### 手动设置证书
+
+你也可以在 `dev.https` 选项中手动传入 HTTPS 服务器所需要的证书和对应的私钥，这个参数将直接传递给 Node.js 中 https 模块的 createServer。
+
+具体可以参考 [https.createServer](https://nodejs.org/api/https.html#https_https_createserver_options_requestlistener)。
+
+```ts
+import fs from 'fs';
+
+export default {
+  dev: {
+    https: {
+      key: fs.readFileSync('certificates/private.pem'),
+      cert: fs.readFileSync('certificates/public.pem'),
+    },
+  },
+};
+```
+
+#### 清理证书缓存
+
+devcert 默认会将生成的证书缓存在 `~/Library/Application\ Support/devcert` ，你可以按需清理。

package/docs/zh/configure/app/dev/lazy-compilation.mdx

@@ -0,0 +1,44 @@
+---
+title: lazyCompilation
+---
+
+# dev.lazyCompilation
+
+- **类型：**
+
+```ts
+type LazyCompilationOptions =
+  | boolean
+  | {
+      /**
+       * 为 entries 启用 lazy compilation
+       */
+      entries?: boolean;
+      /**
+       * 为 dynamic imports 启用 lazy compilation
+       */
+      imports?: boolean;
+      /**
+       * 指定哪些导入的模块应该被延迟编译
+       */
+      test?: RegExp | ((m: Module) => boolean);
+      /**
+       * 指定一个自定义的运行时代码路径，用于覆盖默认的 lazy compilation client
+       */
+      client?: string;
+      /**
+       * 指定 client 需要请求的 server URL
+       */
+      serverUrl?: string;
+    };
+```
+
+- **默认值：** `false`
+
+用于开启 lazy compilation（即按需编译），基于 Rspack 的 [lazy compilation](https://rspack.rs/zh/guide/features/lazy-compilation) 特性实现。
+
+import RsbuildLink from '@site/src/components/RsbuildLink';
+
+:::info
+该配置项的使用方式与 Rsbuild 完全一致，详细信息可参考 <RsbuildLink configName="dev.lazyCompilation"/>。
+:::

package/docs/zh/configure/app/dev/live-reload.mdx

@@ -0,0 +1,14 @@
+---
+title: liveReload
+---
+
+# dev.liveReload
+
+- **类型：** `boolean`
+- **默认值：** `true`
+
+是否在源文件变更时自动刷新页面。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="dev.liveReload" />

package/docs/zh/configure/app/dev/progress-bar.mdx

@@ -0,0 +1,23 @@
+---
+title: progressBar
+---
+
+# dev.progressBar
+
+- **类型：**
+
+```ts
+type ProgressBar =
+  | boolean
+  | {
+      id?: string;
+    };
+```
+
+- **默认值：** true
+
+是否在编译过程中展示进度条。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="dev.progressBar" />