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

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

@@ -0,0 +1,128 @@
+---
+title: server
+---
+
+# dev.server
+
+- **类型：** `Object`
+- **默认值：** `{}`
+
+通过 `dev.server` 可以修改开发环境服务器的配置。
+
+### compress
+
+- **类型：** `boolean`
+- **默认值：** `true`
+
+是否对静态资源启用 gzip 压缩。
+
+如果你需要禁用 gzip 压缩，可以将 `compress` 设置为 `false`：
+
+```ts
+export default {
+  dev: {
+    server: {
+      compress: false,
+    },
+  },
+};
+```
+
+更多详细信息请参考 [Rsbuild - server.compress](https://v2.rsbuild.rs/zh/config/server/compress) 文档。
+
+### headers
+
+- **类型：** `Record<string, string>`
+- **默认值：** `undefined`
+
+设置自定义响应头。
+
+```js
+export default {
+  dev: {
+    server: {
+      headers: {
+        'X-Custom-Foo': 'bar',
+      },
+    },
+  },
+};
+```
+
+更多详细信息请参考 [Rsbuild - server.headers](https://v2.rsbuild.rs/zh/config/server/headers) 文档。
+
+### historyApiFallback
+
+- **类型：** `boolean | ConnectHistoryApiFallbackOptions`
+- **默认值：** `false`
+
+在需要对一些 404 响应或其他请求提供替代页面的场景，可通过 `dev.server.historyApiFallback` 进行设置：
+
+```js
+export default {
+  dev: {
+    server: {
+      historyApiFallback: true,
+    },
+  },
+};
+```
+
+更多配置选项请参考 [Rsbuild - server.historyApiFallback](https://v2.rsbuild.rs/zh/config/server/history-api-fallback) 文档。
+
+### watch
+
+- **类型：** `boolean`
+- **默认值：** `true`
+
+是否监听 `mock/`、`server/`、`api/` 等目录的文件变化。
+
+更多详细信息请参考 [Rsbuild - dev.watchFiles](https://v2.rsbuild.rs/zh/config/dev/watch-files) 文档。
+
+### cors
+
+- **类型:** `boolean | import('cors').CorsOptions`
+
+为开发服务器配置 CORS（跨域资源共享）。
+
+Modern.js 中 `cors` 的默认配置遵循 Rsbuild 的默认值：
+
+```ts
+const defaultAllowedOrigins =
+  /^https?:\/\/(?:(?:[^:]+\.)?localhost|127\.0\.0\.1|\[::1\])(?::\d+)?$/;
+
+const defaultOptions = {
+  // 默认允许：
+  // - localhost
+  // - 127.0.0.1
+  // - [::1]
+  origin: defaultAllowedOrigins,
+};
+```
+
+更多配置选项和详细用法请参考 [Rsbuild - server.cors](https://v2.rsbuild.rs/zh/config/server/cors) 文档。
+
+### proxy
+
+- **类型：** `ProxyOptions[] | Record<string, string | ProxyOptions>`
+- **默认值：** `undefined`
+
+为开发服务器配置代理规则，把请求转发到指定服务。
+
+```js
+export default {
+  dev: {
+    server: {
+      proxy: {
+        // http://localhost:8080/api -> https://example.com/api
+        // http://localhost:8080/api/foo -> https://example.com/api/foo
+        '/api': 'https://example.com',
+      },
+    },
+  },
+};
+```
+
+:::tip
+该选项与 Rsbuild 的 `server.proxy` 选项一致，更多用法请参考 [Rsbuild - server.proxy](https://v2.rsbuild.rs/zh/config/server/proxy)。
+:::

package/docs/zh/configure/app/dev/setup-middlewares.mdx

@@ -0,0 +1,36 @@
+---
+title: setupMiddlewares
+---
+
+# dev.setupMiddlewares
+
+- **类型：**
+
+```ts
+type RequestHandler = (req: any, res: any, next: () => void) => void;
+
+type ExposeServerApis = {
+  sockWrite: (
+    type: string,
+    data?: string | boolean | Record<string, any>,
+  ) => void;
+};
+
+type SetupMiddlewares = Array<
+  (
+    middlewares: {
+      unshift: (...handlers: RequestHandler[]) => void;
+      push: (...handlers: RequestHandler[]) => void;
+    },
+    server: ExposeServerApis,
+  ) => void
+>;
+```
+
+- **默认值：** `undefined`
+
+提供执行自定义函数和应用自定义中间件的能力。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="dev.setupMiddlewares" />

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

@@ -0,0 +1,54 @@
+---
+title: startUrl
+---
+
+# dev.startUrl
+
+- **类型：** `boolean | string | string[] | undefined`
+- **默认值：** `undefined`
+
+`dev.startUrl` 用于设置 Dev Server 启动时自动在浏览器中打开的页面 URL。
+
+默认情况下，Dev Server 启动时不会打开任何页面。
+
+你可以设置为如下的值：
+
+```js
+export default {
+  dev: {
+    // 打开项目的默认页面，等价于 `http://localhost:<port>`
+    startUrl: true,
+    // 打开指定的页面
+    startUrl: 'http://localhost:8080',
+    // 打开多个页面
+    startUrl: ['http://localhost:8080', 'http://localhost:8080/about'],
+  },
+};
+```
+
+### 端口号占位符
+
+由于端口号可能会发生变动，你可以使用 `<port>` 占位符来指代当前端口号，Modern.js 会自动将占位符替换为实际监听的端口号。
+
+```js
+export default {
+  dev: {
+    startUrl: 'http://localhost:<port>/home',
+  },
+};
+```
+
+### 打开指定浏览器
+
+在 MacOS 上，通过设置环境变量 `BROWSER`，你可以指定 Dev Server 在启动时打开的浏览器，支持如下的值：
+
+- Google Chrome Canary
+- Google Chrome Dev
+- Google Chrome Beta
+- Google Chrome
+- Microsoft Edge
+- Brave Browser
+- Vivaldi
+- Chromium
+
+建议设置在`.env.local`文件中。

package/docs/zh/configure/app/dev/watch-files.mdx

@@ -0,0 +1,31 @@
+---
+title: watchFiles
+---
+
+# dev.watchFiles
+
+- **类型：**
+
+```ts
+type WatchFiles =
+  | {
+      paths: string | string[];
+      type?: 'reload-page';
+      //  chokidar 选项
+      options?: WatchOptions;
+    }
+  | {
+      paths: string | string[];
+      type?: 'reload-server';
+    };
+
+type WatchFilesConfig = WatchFiles | WatchFiles[];
+```
+
+- **默认值：** `undefined`
+
+监听指定文件和目录的变化。当文件发生变化时，可以触发页面的重新加载，或者触发 dev server 重新启动。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="dev.watchFiles" />

package/docs/zh/configure/app/dev/write-to-disk.mdx

@@ -0,0 +1,14 @@
+---
+title: writeToDisk
+---
+
+# dev.writeToDisk
+
+- **类型：** `boolean | ((filename: string) => boolean)`
+- **默认值：** `(file: string) => !file.includes('.hot-update.')`
+
+用于控制是否将开发环境的构建产物写入到磁盘上。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="dev.writeToDisk" />

package/docs/zh/configure/app/experiments/source-build.mdx

@@ -0,0 +1,35 @@
+---
+title: sourceBuild
+---
+
+# experiments.sourceBuild
+
+- **类型：** `boolean | PluginSourceBuildOptions`
+- **默认值：** `false`
+
+用于开启源码构建的能力。当开启此配置项时，Modern.js 会读取子项目 package.json 的 `source` 字段对应的源码文件，并进行编译。
+
+```ts
+export default {
+  experiments: {
+    sourceBuild: true,
+  },
+};
+```
+
+更多信息可参考[「源码构建模式」](https://modernjs.dev/guides/advanced-features/source-build.html)。
+
+### 选项
+
+`experiments.sourceBuild` 底层基于 [@rsbuild/plugin-source-build](https://github.com/rspack-contrib/rsbuild-plugin-source-build?tab=readme-ov-file#options) 实现，你可以传入插件选项，比如：
+
+```ts
+export default {
+  experiments: {
+    sourceBuild: {
+      sourceField: 'my-source',
+      resolvePriority: 'output',
+    },
+  },
+};
+```

package/docs/zh/configure/app/html/app-icon.mdx

@@ -0,0 +1,32 @@
+---
+title: appIcon
+---
+
+# html.appIcon
+
+- **类型：**
+
+```ts
+type AppIconItem = {
+  src: string;
+  size: number;
+  target?: 'apple-touch-icon' | 'web-app-manifest';
+};
+
+type AppIcon = {
+  name?: string;
+  icons: AppIconItem[];
+  filename?: string;
+};
+```
+
+- **默认值：** `undefined`
+
+设置 Web 应用的图标，用于在添加到移动设备的主屏幕时显示：
+
+- 生成 web app manifest 文件和其中的 `icons` 字段。
+- 生成 HTML 文件中的 `apple-touch-icon` 标签和 `manifest` 标签。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="html.appIcon" />

package/docs/zh/configure/app/html/crossorigin.mdx

@@ -0,0 +1,15 @@
+---
+title: crossorigin
+---
+
+# html.crossorigin
+
+- **类型：** `boolean | 'anonymous' | 'use-credentials'`
+- **默认值：** `false`
+
+用于设置 `<script>` 和 `<style>` 标签的 [crossorigin](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) 属性。
+
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="html.crossorigin" />

package/docs/zh/configure/app/html/favicon.mdx

@@ -0,0 +1,21 @@
+---
+title: favicon
+---
+
+# html.favicon
+
+- **类型：** `string ｜ Function`
+- **默认值：** `undefined`
+
+设置页面的 favicon 图标，可以设置为：
+
+- URL 地址。
+- 文件的绝对路径。
+- 相对于项目根目录的相对路径。
+
+配置该选项后，在编译过程中会自动将图标拷贝至 dist 目录下，并在 HTML 中添加相应的 `link` 标签。
+
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="html.favicon" />

package/docs/zh/configure/app/html/inject.mdx

@@ -0,0 +1,14 @@
+---
+title: inject
+---
+
+# html.inject
+
+- **类型：** `'head' | 'body' | boolean | Function`
+- **默认值：** `'head'`
+
+修改构建产物中 `<script>` 标签在 HTML 中的插入位置。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="html.inject" />

package/docs/zh/configure/app/html/meta.mdx

@@ -0,0 +1,28 @@
+---
+title: meta
+---
+
+# html.meta
+
+- **类型：** `Object | Function`
+- **默认值：**
+
+```js
+const defaultMeta = {
+  charset: { charset: 'utf-8' },
+  viewport:
+    'width=device-width, initial-scale=1.0, shrink-to-fit=no, viewport-fit=cover, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no',
+  'http-equiv': { 'http-equiv': 'x-ua-compatible', content: 'ie=edge' },
+  renderer: 'webkit',
+  layoutmode: 'standard',
+  imagemode: 'force',
+  'wap-font-scale': 'no',
+  'format-detection': 'telephone=no',
+};
+```
+
+配置 HTML 页面的 `<meta>` 标签。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="html.meta" />

package/docs/zh/configure/app/html/mount-id.mdx

@@ -0,0 +1,14 @@
+---
+title: mountId
+---
+
+# html.mountId
+
+- **类型：** `string`
+- **默认值：** `'root'`
+
+默认情况下，HTML 模板中包含了 `root` 节点用于组件挂载，通过 `mountId` 可以修改该节点的 id。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="html.mountId" />

package/docs/zh/configure/app/html/output-structure.mdx

@@ -0,0 +1,14 @@
+---
+title: outputStructure
+---
+
+# html.outputStructure
+
+- **类型：** `'flat' | 'nested'`
+- **默认值：** `'nested'`
+
+用于定义 HTML 产物文件的目录结构。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="html.outputStructure" />

package/docs/zh/configure/app/html/script-loading.mdx

@@ -0,0 +1,14 @@
+---
+title: scriptLoading
+---
+
+# html.scriptLoading
+
+- **类型：** `'defer' | 'blocking' | 'module'`
+- **默认值：** `'defer'`
+
+用于设置 `<script>` 标签的加载方式。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="html.scriptLoading" />

package/docs/zh/configure/app/html/tags.mdx

@@ -0,0 +1,19 @@
+---
+title: tags
+---
+
+# html.tags
+
+- **类型：**
+
+```ts
+type TagsConfig = HtmlTag | HtmlTagHandler | Array<HtmlTag | HtmlTagHandler>;
+```
+
+- **默认值：** `undefined`
+
+添加和修改最终注入到 HTML 页面的标签。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="html.tags" />

package/docs/zh/configure/app/html/template-parameters.mdx

@@ -0,0 +1,37 @@
+---
+title: templateParameters
+---
+
+# html.templateParameters
+
+- **类型：** `Record<string, unknown> | Function`
+- **默认值：**
+
+```ts
+type DefaultParameters = {
+  mountId: string; // 对应 html.mountId 配置
+  entryName: string; // 入口名称
+  assetPrefix: string; // 对应 dev.assetPrefix 和 output.assetPrefix 配置
+  compilation: Compilation; // Rspack 的 compilation 对象
+  rspackConfig: Rspack.Configuration; // Rspack 的配置对象
+  // html-rspack-plugin 生成的参数
+  htmlPlugin: {
+    tags: {
+      headTags: HtmlTagObject[];
+      bodyTags: HtmlTagObject[];
+    };
+    files: {
+      publicPath: string;
+      js: Array<string>;
+      css: Array<string>;
+      favicon?: string;
+    };
+  };
+};
+```
+
+定义 HTML 模板中的参数，对应 [html-rspack-plugin](https://github.com/rspack-contrib/html-rspack-plugin) 的 `templateParameters` 配置项。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="html.templateParameters" />

package/docs/zh/configure/app/html/template.mdx

@@ -0,0 +1,14 @@
+---
+title: template
+---
+
+# html.template
+
+- **类型：** `string | Function`
+- **默认值：**
+
+定义 HTML 模板的文件路径，可以是相对路径或绝对路径。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="html.template" />

package/docs/zh/configure/app/html/title.mdx

@@ -0,0 +1,22 @@
+---
+title: title
+---
+
+# html.title
+
+- **类型：** `string | Function`
+- **默认值：** `''`
+
+配置 HTML 页面的 title 标签，例如：
+
+```js
+export default {
+  html: {
+    title: 'example',
+  },
+};
+```
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="html.title" />

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

@@ -0,0 +1,18 @@
+---
+title: assetPrefix
+---
+
+# output.assetPrefix
+
+- **类型：** `string`
+- **默认值：** `'/'`
+
+在生产环境使用 CDN 部署时，可使用该选项设置静态资源的 URL 前缀。
+
+import OutputAssetPrefixExtend from '@site-docs/components/output-asset-prefix-extend';
+
+<OutputAssetPrefixExtend />
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="output.assetPrefix" />

package/docs/zh/configure/app/output/assets-retry.mdx

@@ -0,0 +1,81 @@
+---
+title: assetsRetry
+---
+
+# output.assetsRetry
+
+- **类型：** `Object`
+
+`output.assetsRetry` 用于配置资源加载失败时的重试逻辑。配置类型如下:
+
+```ts
+export type AssetsRetryHookContext = {
+  times: number;
+  domain: string;
+  url: string;
+  tagName: string;
+};
+
+export type AssetsRetryOptions = {
+  type?: string[];
+  domain?: string[];
+  max?: number;
+  test?: string | ((url: string) => boolean);
+  crossOrigin?: boolean | 'anonymous' | 'use-credentials';
+  inlineScript?: boolean;
+  onRetry?: (options: AssetsRetryHookContext) => void;
+  onSuccess?: (options: AssetsRetryHookContext) => void;
+  onFail?: (options: AssetsRetryHookContext) => void;
+};
+```
+
+- **默认值：** `undefined`
+
+由于该能力会往 HTML 中和 [Rspack Runtime](https://rspack.rs/api/runtime-api/module-variables) 注入额外的一些运行时代码，因此我们默认关闭了该能力，如果需要开启该能力，你可以添加以下配置：
+
+```js
+export default {
+  output: {
+    assetsRetry: {},
+  },
+};
+```
+
+当你开启该能力后，`assetsRetry` 的默认配置如下：
+
+```ts
+export const defaultAssetsRetryOptions: AssetsRetryOptions = {
+  type: ['script', 'link', 'img'],
+  domain: [],
+  max: 3,
+  test: '',
+  crossOrigin: false,
+  inlineScript: false,
+  onRetry: () => {},
+  onSuccess: () => {},
+  onFail: () => {},
+};
+```
+
+### 示例
+
+你可以通过 `assetsRetry` 配置项，来定制你的重试逻辑。
+
+如，通过 `assetsRetry.domain` 指定资源加载失败时的重试域名列表，第一个域名应该与 [`assetsPrefix`](./asset-prefix.mdx) 配置中的域名保持一致：
+
+```js
+export default {
+  output: {
+    assetsRetry: {
+      domain: ['cdn1.com', 'cdn2.com', 'cdn3.com'],
+    },
+    assetsPrefix: 'https://cdn1.com', // 或 '//cdn1.com'
+  },
+};
+```
+
+添加以上配置后，当 `cdn1.com` 域名的资源加载失败时，请求域名会自动降级到 `cdn2.com`。
+
+如果 `cdn2.com` 的资源也请求失败，则会继续请求 `cdn3.com`。
+
+`assetsRetry` 是基于 Rsbuild 的 Assets Retry 插件实现的，并提供相同的配置项。你可以参考 [Rsbuild - Assets Retry 插件](https://github.com/rstackjs/rsbuild-plugin-assets-retry) 来了解所有可用的配置项。

package/docs/zh/configure/app/output/charset.mdx

@@ -0,0 +1,14 @@
+---
+title: charset
+---
+
+# output.charset
+
+- **类型：** `'ascii' | 'utf8'`
+- **默认值：** `'ascii'`
+
+`charset` 配置项允许你指定输出文件的[字符编码](https://developer.mozilla.org/en-US/docs/Glossary/Character_encoding) 字符编码，以确保它们在不同的环境中能够正确显示。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="output.charset" />