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

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

@@ -0,0 +1,14 @@
+---
+title: removeMomentLocale
+---
+
+# performance.removeMomentLocale
+
+- **类型：** `boolean`
+- **默认值：** `false`
+
+是否移除 [moment.js](https://momentjs.com/) 的语言包文件。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="performance.removeMomentLocale" />

package/docs/zh/configure/app/performance/rsdoctor.mdx

@@ -0,0 +1,39 @@
+---
+title: rsdoctor
+---
+
+# performance.rsdoctor
+
+- **类型：**
+
+```ts
+type RsdoctorConfig =
+  | boolean
+  | {
+      enabled?: boolean;
+    };
+```
+
+- **默认值：** 生产构建时为 `true`，开发模式下为 `false`。
+
+用于配置 Modern.js 构建过程中的 Rsdoctor 诊断能力。
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  performance: {
+    rsdoctor: false,
+  },
+});
+```
+
+你也可以使用对象形式：
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  performance: {
+    rsdoctor: {
+      enabled: true,
+    },
+  },
+});
+```

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

@@ -0,0 +1,59 @@
+# plugins
+
+- **类型：** `CliPlugin[]`
+- **默认值：** `[]`
+
+用于配置自定义的 Modern.js 框架 CLI 插件。自定义 CLI 插件的编写方式请参考 [如何编写 CLI 插件](/plugin/introduction.html#cli-插件)。
+
+## 注意事项
+
+该选项**用于配置框架 CLI 插件**，如果你需要配置其他类型的插件，请选择对应的配置方式：
+
+- 配置 Rsbuild 插件，请使用 [builderPlugins](/configure/app/builder-plugins) 配置项。
+- 配置 Rspack 插件，请使用 [tools.bundlerChain](/configure/app/tools/bundler-chain) 配置项。
+- 配置框架 Runtime 插件，请使用 [runtime 配置文件 plugins](/configure/app/runtime/plugins) 配置项。
+
+## 示例
+
+下面是 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/docs/zh/configure/app/resolve/alias-strategy.mdx

@@ -0,0 +1,14 @@
+---
+title: aliasStrategy
+---
+
+# resolve.aliasStrategy
+
+- **类型:** `'prefer-tsconfig' | 'prefer-alias'`
+- **默认值:** `'prefer-tsconfig'`
+
+设置路径别名解析的策略，用于控制 `tsconfig.json` 中的 paths 选项与 Rsbuild 的 [resolve.alias](https://v2.rsbuild.rs/config/resolve/alias) 选项之间的优先级关系。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="resolve.aliasStrategy" />

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

@@ -0,0 +1,13 @@
+---
+title: alias
+---
+
+# resolve.alias
+
+- **类型:** `string[]`
+
+设置模块路径的别名，用于简化导入路径或重定向模块引用。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="resolve.alias" />

package/docs/zh/configure/app/resolve/condition-names.mdx

@@ -0,0 +1,18 @@
+---
+title: conditionNames
+---
+
+# resolve.conditionNames
+
+- **类型:** `string[]`
+- **默认值:** 与 Rsbuild 的 `resolve.conditionNames` 一致
+
+指定用于匹配包 [exports](https://nodejs.org/api/packages.html#packages_exports) 字段 入口点的 condition names（条件名称）。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="resolve.extensions" />
+
+:::warning
+SSR 应用请勿启用此配置项，否则会导致 SSR 渲染失败。
+:::

package/docs/zh/configure/app/resolve/dedupe.mdx

@@ -0,0 +1,14 @@
+---
+title: dedupe
+---
+
+# resolve.dedupe
+
+- **类型:** `string[]`
+
+强制 Rsbuild 从项目根目录解析指定的包，这可以用于移除重复包和减少包大小。对应 Rsbuild 的 [resolve.dedupe](https://v2.rsbuild.rs/config/resolve/dedupe) 配置。
+
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="resolve.dedupe" />

package/docs/zh/configure/app/resolve/extensions.mdx

@@ -0,0 +1,18 @@
+---
+title: extensions
+---
+
+# resolve.extensions
+
+- **类型:** `string[]`
+- **默认值:** `['.ts', '.tsx', '.mjs', '.js', '.jsx', '.json']`
+
+自动添加导入文件的扩展名。这意味着你可以导入文件，而不需要显式地写它们的扩展名。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="resolve.extensions" />
+
+:::warning
+SSR 应用请勿启用此配置项，否则会导致 SSR 渲染失败。
+:::

package/docs/zh/configure/app/runtime/0-intro.mdx

@@ -0,0 +1,58 @@
+# 介绍
+
+Modern.js 的运行时（Runtime）配置需集中在 `src/modern.runtime.ts` 文件中声明。
+
+:::info
+如果项目中还没有此文件，请执行以下命令创建：
+
+```bash
+touch src/modern.runtime.ts
+```
+
+:::
+
+## 基本配置
+
+```tsx
+import { defineRuntimeConfig } from '@modern-js/runtime';
+
+export default defineRuntimeConfig({
+  router: {
+    // 路由配置
+  },
+  // 其他运行时模块...
+});
+```
+
+## 多入口配置
+
+对于多入口应用，`defineRuntimeConfig` 函数可以根据入口名称返回特定的配置：
+
+```tsx
+import { defineRuntimeConfig } from '@modern-js/runtime';
+
+export default defineRuntimeConfig(entryName => {
+  if (entryName === 'main') {
+    return {
+      router: {
+        // "main" 入口的路由配置
+      },
+    };
+  }
+
+  // 其他入口的配置
+  return {
+    router: {
+      // 其他入口的路由配置
+    },
+  };
+});
+```
+
+:::tip
+使用 `src/modern.runtime.ts` 配置方式不支持导出异步函数，这与 Modern.js 的渲染方式有关。如果需要添加异步逻辑，请使用 **[Runtime 插件 (Runtime Plugin)](/plugin/introduction.html#runtime-插件)**。
+:::
+
+import RuntimeCliConfig from '@site-docs/components/runtime-cli-config';
+
+<RuntimeCliConfig />

package/docs/zh/configure/app/runtime/plugins.mdx

@@ -0,0 +1,58 @@
+# plugins
+
+- **类型：** `RuntimePlugin[]`
+- **默认值：** `[]`
+
+用于配置自定义的 Modern.js Runtime 插件。自定义 Runtime 插件的编写方式请参考 [如何编写 Runtime 插件](/plugin/introduction.html#runtime-插件)。
+
+:::info
+
+Runtime 插件需要在 `src/modern.runtime.ts` 文件中的 plugins 中进行配置。
+
+:::
+
+## 示例
+
+下面是 Runtime 插件的使用示例。
+
+### 使用 npm 上的插件
+
+使用 npm 上的插件，需要通过包管理器安装插件，并通过 import 引入。
+
+```ts title="src/modern.runtime.ts"
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import { myPlugin } from 'my-plugin';
+
+export default defineRuntimeConfig({
+  plugins: [myPlugin()],
+});
+```
+
+### 使用本地插件
+
+使用本地代码仓库中的插件，直接通过相对路径 import 引入即可。
+
+```ts title="src/modern.runtime.ts"
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import { myPlugin } from './config/plugin/myPlugin';
+
+export default defineRuntimeConfig({
+  plugins: [myPlugin()],
+});
+```
+
+### 插件配置项
+
+如果插件提供了一些自定义的配置项，可以通过插件函数的参数传入配置。
+
+```ts title="src/modern.runtime.ts"
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import { myPlugin } from './config/plugin/myPlugin';
+
+export default defineRuntimeConfig({
+  plugins: [myPlugin({
+    foo: 1,
+    bar: 2,
+  })],
+});
+```

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

@@ -0,0 +1,39 @@
+---
+title: router
+---
+
+# router
+
+- **类型：** `Object`
+- **默认值：** `{}`
+
+该配置项用于配置客户端路由，支持使用 Modern.js 默认提供的[约定式路由](/guides/concept/entries.html#约定式路由)进行路由管理。
+
+:::note
+`router` 配置项**仅在使用约定式路由入口时生效**（即入口中存在 `routes/` 目录）。对于自控式路由入口或自定义入口，该配置不会生效。
+
+在多入口应用中，可以通过 `defineRuntimeConfig` 的函数形式为不同入口配置不同的路由行为，详见[运行时配置介绍](/configure/app/runtime/0-intro#多入口配置)。
+:::
+
+## basename
+
+- **类型：** `string`
+- **默认值：** `/`
+
+设置客户端路由的 `basename`，通常用于应用需要部署在域名非根路径下的场景。
+
+:::tip
+推荐使用 [`server.baseUrl`](/configure/app/server/base-url) 进行配置。
+:::
+
+## supportHtml5History
+
+- **类型：** `boolean`
+- **默认值：** `true`
+
+值为 `true`，使用 `BrowserRouter`；否则使用 `HashRouter`。推荐使用 `BrowserRouter`。
+
+:::warning
+当开启 SSR 时，不支持设置 `supportHtml5History`。
+
+:::

package/docs/zh/configure/app/security/check-syntax.mdx

@@ -0,0 +1,73 @@
+---
+title: checkSyntax
+---
+
+# security.checkSyntax
+
+- **类型：**
+
+```ts
+type CheckSyntax =
+  | boolean
+  | {
+      targets?: string[];
+      exclude?: RegExp | RegExp[];
+      ecmaVersion?: EcmaVersion;
+    };
+```
+
+- **默认值：** `false`
+
+用于分析构建产物中是否存在当前浏览器范围下不兼容的高级语法。如果存在，会将详细信息打印在终端。
+
+### 启用检测
+
+你可以将 `checkSyntax` 设置为 `true` 来启用语法检测。
+
+```ts
+export default {
+  security: {
+    checkSyntax: true,
+  },
+};
+```
+
+当你开启 `checkSyntax` 后，Modern.js 会在生产环境构建时进行检测，当在构建产物中检测到不兼容的高级语法后，会将错误日志打印在终端，并退出当前构建流程。
+
+### 错误日志
+
+错误日志的格式如下所示，包含代码来源文件、产物位置、错误原因、源代码等信息：
+
+```bash
+error   [Syntax Checker] Find some syntax errors after production build:
+
+  Error 1
+  source:  /node_modules/foo/index.js:1:0
+  output:  /dist/static/js/main.3f7a4d7e.js:2:39400
+  reason:  Unexpected token (1:178)
+  code:
+     9 |
+    10 | var b = 2;
+    11 |
+  > 12 | console.log(() => {
+    13 |   return a + b;
+    14 | });
+    15 |
+```
+
+:::tip
+目前语法检测是基于 AST parser 来实现的，每次检测时，只能找出文件中的第一个不兼容语法。如果一个文件中存在多个不兼容语法，你需要修复已发现的语法，并重新执行检测。
+如果日志中没有显示对应的源码位置，可以尝试将 **output.minify** 设置为 false 后再重新构建。
+:::
+
+### 解决方法
+
+当检测到语法错误后，你可以通过以下方式来处理：
+
+- 如果你希望降级该语法，以保证代码具备良好的兼容性，可以通过 `source.include` 配置来编译相应的模块。
+- 如果你不希望降级该语法，可以调整项目的 browserslist 范围，调整至与该语法相匹配的范围。
+- 如果你不希望对某些产物进行语法检查，可用 `checkSyntax.exclude` 配置排除要检查的文件。
+
+### 选项
+
+`security.checkSyntax` 底层基于 `@rsbuild/plugin-check-syntax` 实现，具体选项可参考 [@rsbuild/plugin-check-syntax](https://github.com/rspack-contrib/rsbuild-plugin-check-syntax)。

package/docs/zh/configure/app/security/nonce.mdx

@@ -0,0 +1,19 @@
+---
+title: nonce
+---
+
+# security.nonce
+
+- **类型：**
+
+```ts
+type Nonce = string;
+```
+
+- **默认值：** `undefined`
+
+为 HTML 所引入的脚本资源添加随机属性值 nonce，使浏览器在解析到带有匹配 nonce 值的内联脚本时，能判断该脚本是否能执行。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="security.nonce" />

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

@@ -0,0 +1,24 @@
+---
+title: sri
+---
+
+# security.sri
+
+- **类型：**
+
+```ts
+type SriOptions = {
+  hashFuncNames?: [string, ...string[]];
+  enabled?: 'auto' | true | false;
+};
+```
+
+- **默认值：** `undefined`
+
+为 HTML 所引入的 `<script>` 和 `<link rel="stylesheet">` 标签添加完整性属性 —— `integrity`，使浏览器能够验证引入资源的完整性，以此防止下载的资源被篡改。
+
+:::info
+SRI 的具体介绍可以参考 [Rsbuild security.sri](https://v2.rsbuild.rs/zh/config/security/sri)。
+
+该配置类型和 Rsbuild 不完全一致，在构建时将自动进行转换。
+:::

package/docs/zh/configure/app/server/base-url.mdx

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

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

@@ -0,0 +1,23 @@
+---
+title: port
+---
+
+# server.port
+
+- **类型：** `number`
+- **默认值：** `8080`
+
+Modern.js 在执行 `dev` 和 `serve` 命令时，会以 `8080` 为默认端口启动，并会在端口被占用时自动递增端口号。你可以通过该配置来修改 Server 启动的端口号：
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    port: 3000,
+  },
+});
+```
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="server.port" />
+```

package/docs/zh/configure/app/server/public-routes.mdx

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

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

@@ -0,0 +1,90 @@
+---
+title: routes
+---
+
+# server.routes
+
+- **类型：** `Object`
+- **默认值：** 根据文件约定自动生成的服务端路由规则，每个入口生成一条路由规则，入口名称等于路由路径。
+
+该配置选项只作用于服务端路由，可以自定义应用入口的访问路由。
+
+## 自定义访问路由
+
+对象的 `key` 为当前应用的入口名, 值可以是 `string | Array<string>`。
+
+当值类型为 `string` 时，当前值即表示访问该入口的路由名称。
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    routes: {
+      // 默认路由为 /entryName1，自定义后为 /p/test1
+      entryName1: '/p/test1'
+      // 支持动态服务端路由配置
+      entryName2: '/detail/:id'
+    }
+  }
+});
+```
+
+也可以通过 `Array<string>` 为入口设置多个访问路由:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    routes: {
+      'page-a': [`/a`, '/b'],
+    },
+  },
+});
+```
+
+此时，通过 `/a`、`/b` 两个路由都可以访问到 `page-a` 入口。
+
+执行 `dev` 命令后，可以在 `dist/route.json` 中查看入口 `page-a` 存在两条路由记录:
+
+```json
+{
+  "routes": [
+    {
+      "urlPath": "/a",
+      "entryName": "page-a",
+      "entryPath": "html/page-a/index.html",
+      "isSPA": true,
+      "isSSR": false
+    },
+    {
+      "urlPath": "/b",
+      "entryName": "page-a",
+      "entryPath": "html/page-a/index.html",
+      "isSPA": true,
+      "isSSR": false
+    }
+  ]
+}
+```
+
+## 自定义响应头
+
+可以通过配置入口的 resHeaders 设置响应头：
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    routes: {
+      'page-a': {
+        route: ['/a', '/b'],
+        resHeaders: {
+          'x-modern-test': '1',
+        },
+      },
+    },
+  },
+});
+```
+
+:::note
+这一配置在生产环境与开发环境都生效，可以根据 NODE_ENV 区分环境设置不同的响应头。但如果你只需要在开发环境设置响应头，推荐使用 `tools.devServer.headers`。
+
+:::

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

@@ -0,0 +1,30 @@
+---
+title: rsc
+---
+
+# server.rsc
+
+- **类型：** `boolean`
+- **默认值：** `false`
+
+启用 React Server Components (RSC) 配置。
+
+当设置为 `true` 时，启用 Modern.js 的 React Server Components 支持。这允许组件在服务端渲染，提供更好的性能和开发体验。
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    rsc: true,
+  },
+});
+```
+
+:::tip 前置条件
+在启用 RSC 之前，请确保：
+1. React 和 React DOM 已升级到 19 版本（建议 19.2.4 以上版本）
+2. 已安装 `react-server-dom-rspack@0.0.1-beta.1` 依赖
+
+:::
+
+有关使用 RSC 的更多信息，请参阅 [React Server Components 指南](/guides/basic-features/render/rsc)。
+