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

package/docs/zh/guides/advanced-features/bff/sdk.mdx

@@ -0,0 +1,117 @@
+# 扩展一体化调用 SDK
+
+BFF 函数的一体化调用在 CSR 和 SSR 是同构的。Modern.js 封装的请求 SDK，在浏览器端依赖了 [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch)，在服务端依赖了 [node-fetch](https://www.npmjs.com/package/node-fetch)。但在实际业务场景下，有时需要对请求或响应做一些额外的处理，例如：
+
+- 在请求头中写入鉴权信息
+- 对响应的数据或错误进行统一的处理
+- 特定平台无法使用浏览器的原生 fetch 函数，需要使用其他方式发送请求
+
+针对上述的场景，Modern.js 提供了 `configure` 函数，开放了一系列扩展能力，可以用它配置 ssr 透传请求头，添加拦截器，自定义请求 SDK。
+
+:::caution 注意
+`configure` 函数的调用需要在所有 BFF 请求发送前调用，以确保覆盖默认的请求配置。
+
+:::
+
+```tsx title="routes/page.tsx"
+import { configure } from '@modern-js/plugin-bff/client';
+
+configure({
+  // ...
+});
+
+const Index = () => <div>Hello world</div>;
+export default Index;
+```
+
+## 配置 SSR 透传请求头
+
+在同时使用 Modern.js SSR 和 BFF 的场景下，常常需要将 SSR 页面请求上的一些请求头信息，透传给 BFF 服务。
+
+例如项目有页面地址是 `https://website.com`，该页面是 SSR 的，在组件中会调用 API 接口 `https://website.com/api/info`，该接口需要用户的 cookie 信息做鉴权。页面在请求该 API 接口时，需要将 SSR 页面请求的 `cookie` 传给 BFF。
+
+目前以下请求头在 Modernjs 中是自动透传的：
+
+```ts
+['cookie', 'user-agent', 'x-tt-logid', 'x-tt-stress'];
+```
+
+可以通过 `configure` 配置请求头。例如以下例子，Modern.js 会自动将 SSR 页面请求的 `x-uid` 信息透传给 BFF 服务：
+
+```tsx
+configure({
+  allowedHeaders: ['x-uid'],
+});
+```
+
+## 添加拦截器
+
+在有些业务场景下需要对请求和响应进行统一的处理，这种场景下可以通过**配置拦截器**满足需求：
+
+```tsx
+configure({
+  // 这里的 request 是一体化默认的请求工具，interceptor 函数需返回一个新的 request。
+  // 新 request 的出参必须是 parse body 之后的结果
+  interceptor(request) {
+    return async (url, params) => {
+      const res = await request(url, params);
+      // 拦截器可能返回 Response 对象，需要手动解析 JSON
+      if (res instanceof Response) {
+        return res.json();
+      }
+      // 如果已经是解析后的数据，直接返回
+      return res;
+    };
+  },
+});
+```
+
+## 自定义请求 SDK
+
+如果仅仅通过配置拦截器无法满足需求，希望自定义请求函数，也可以通过 `configure` 进行配置：
+
+```tsx
+import nodeFetch from 'node-fetch';
+
+const customFetch = (input: RequestInfo | URL, init: RequestInit) => {
+  const curFetch =
+    process.env.MODERN_TARGET !== 'node'
+      ? fetch
+      : (nodeFetch as unknown as typeof fetch);
+  return curFetch(input, init).then(async res => {
+    const data = await res.json();
+    data.hello = 'hello custom sdk';
+    return data;
+  });
+};
+
+configure({
+  request: customFetch,
+});
+```
+
+配置自定义请求函数有以下约定：
+
+- 函数的入参与浏览器中的 Fetch 或 node-fetch 对齐，所有 BFF 函数的一体化调用会通过该函数发送请求。
+- 函数出参必须是接口实际返回的数据，不能是 Promise，否则会导致 BFF 函数无法正常返回数据。
+- 如果是 SSR 项目，函数必须要同时支持浏览器端和服务器端发送请求。
+
+下面是使用 axios 定制自定义请求函数的示例：
+
+```tsx title="App.tsx"
+import { configure } from '@modern-js/plugin-bff/client';
+import type { Method, AxiosRequestHeaders as Headers } from 'axios';
+
+configure({
+  async request(...config: Parameters<typeof fetch>) {
+    const [url, params] = config;
+    const res = await axios({
+      url: url as string, // 这里因为 fetch 和 axios 类型有些不兼容，需要使用 as
+      method: params?.method as Method,
+      data: params?.body,
+      headers: params?.headers as Headers,
+    });
+    return res.data;
+  },
+});
+```

package/docs/zh/guides/advanced-features/bff/upload.mdx

@@ -0,0 +1,7 @@
+# 文件上传
+
+BFF 搭配运行时框架提供了文件上传能力，支持一体化调用及纯函数手动调用。
+
+import BffUpload from '@site-docs/components/bff-upload';
+
+<BffUpload />

package/docs/zh/guides/advanced-features/bff.mdx

@@ -0,0 +1,21 @@
+---
+title: BFF
+---
+# BFF
+
+BFF（Backends for Frontends）是一种架构模式，主要用于解决前后端协作中的数据聚合问题。在 BFF 架构下，前端应用程序不直接与后端服务通信，而是通过一个专门为前端定制的BFF中间层与后端服务交互。
+
+它的适用场景包括：
+
+- 根据自身业务需求，对更底层 API 的聚合、映射、裁剪、代理。
+- 对一些特定场景的数据进行缓存，提高性能，进而提升用户体验。
+- 根据已有接口快速开发新产品。
+- 与第三方系统对接，例如登陆鉴权。
+
+Modern.js 官方支持了 BFF，并提供了**一体化 BFF 方案**来进一步强化 BFF 能力，主要包括以下能力：
+
+- 快速开发调试上线，在同一项目中运行、构建、部署 BFF 代码。
+- 极简的纯函数调用，在前端直接 import BFF 函数，调用时能自动转换成 HTTP 请求。
+- 无私有协议，遵循 RESTful API 规范，所有 BFF 接口都是标准化的。
+- 完善的 TypeScript 支持。
+- 满足用户使用偏好，支持多框架扩展写法。

package/docs/zh/guides/advanced-features/build-performance.mdx

@@ -0,0 +1,134 @@
+---
+sidebar_position: 12
+---
+
+# 提升构建性能
+
+Modern.js 默认对构建性能进行了充分优化，但是随着业务场景变复杂、项目代码量变大，你可能会遇到一些构建性能的问题。
+
+本文档提供了一些可选的提速策略，**开发者可以根据实际场景选取其中的部分策略**，从而进一步提升构建速度。
+
+:::tip 📢 注意
+在[优化产物体积](/guides/advanced-features/page-performance/optimize-bundle)一文中介绍的策略也可以用于提升构建性能，这里不再重复介绍。
+:::
+
+## 通用优化策略
+
+以下是一些通用的优化策略，对开发环境和生产环境均有提速效果，其中部分策略对包体积也有优化。
+
+### 升级 Node.js 版本
+
+通常来说，将 Node.js 更新到最新的 [LTS 版本](https://github.com/nodejs/release#release-schedule)，有助于提升构建性能。
+
+Modern.js 要求 Node.js 版本 >= 20.19.5，我们强烈推荐使用最新的 LTS 版本（如 Node.js 22 LTS）以获得最佳构建性能。
+
+你可以通过以下步骤来切换到最新的 LTS 版本：
+
+```bash
+# 安装最新的 LTS 版本（例如 Node.js 22）
+nvm install --lts
+
+# 切换到最新 LTS 版本
+nvm use --lts
+
+# 将最新 LTS 版本设置为默认版本
+nvm alias default lts/*
+
+# 查看 Node 版本
+node -v
+```
+
+或者指定安装 Node.js 22 LTS：
+
+```bash
+# 安装 Node.js 22 LTS
+nvm install 22 --lts
+
+# 切换到 Node.js 22
+nvm use 22
+
+# 将 Node.js 22 设置为默认版本
+nvm alias default 22
+
+# 查看 Node 版本
+node -v
+```
+
+## 开发环境优化策略
+
+以下是针对开发环境进行提速的策略。
+
+### 调整 Source Map 格式
+
+为了提供良好的调试体验，Modern.js 在开发环境下默认使用 `cheap-module-source-map` 格式 Source Map，这是一种高质量的 Source Map 格式，会带来一定的性能开销。
+
+你可以通过调整开发环境的 Source Map 格式来提升构建速度。
+
+比如禁用 Source Map：
+
+```js
+export default {
+  tools: {
+    bundlerChain(chain, { env }) {
+      if (env === 'development') {
+        chain.devtool(false);
+      }
+    },
+  },
+};
+```
+
+或是把开发环境的 Source Map 格式设置为开销最小的 `eval` 格式：
+
+```js
+export default {
+  tools: {
+    bundlerChain(chain, { env }) {
+      if (env === 'development') {
+        chain.devtool('eval');
+      }
+    },
+  },
+};
+```
+
+> 关于不同 Source Map 格式之间的详细差异，请查看 [rspack - devtool](https://rspack.rs/zh/config/devtool)。
+
+### 调整 Browserslist 范围
+
+这项优化的原理与[「提升 Browserslist 范围」](/guides/advanced-features/page-performance/optimize-bundle#提升-browserslist-范围)类似，区别在于，我们可以为开发环境和生产环境设置不同的 browserslist，从而减少开发环境下的编译开销。
+
+比如，你可以在 `package.json` 中添加以下配置，表示在开发环境下只兼容最新的浏览器，在生产环境下兼容实际需要的浏览器：
+
+```json
+{
+  "browserslist": {
+    "production": [">0.2%", "not dead", "not op_mini all"],
+    "development": [
+      "last 1 chrome version",
+      "last 1 firefox version",
+      "last 1 safari version"
+    ]
+  }
+}
+```
+
+注意，这项优化策略会导致开发环境与生产环境的构建产物存在一定差异。
+
+## 生产环境优化策略
+
+以下是针对生产环境进行提速的策略。
+
+### 禁用 Source Map
+
+如果项目在生产环境下不需要 Source Map，可以通过 `sourceMap` 配置项关闭，从而提升 build 构建的速度。
+
+```js
+export default {
+  output: {
+    sourceMap: false,
+  },
+};
+```
+
+详见 [output.sourceMap](/configure/app/output/source-map.html)。

package/docs/zh/guides/advanced-features/compatibility.mdx

@@ -0,0 +1,80 @@
+---
+sidebar_position: 6
+---
+
+# 浏览器兼容性
+
+## Browserslist 配置
+
+Modern.js 支持通过三种方式来设置 Web 应用需要兼容的浏览器范围。
+
+### 方式一：通过`.browserslistrc` 文件配置
+
+Modern.js 支持设置 Web 应用需要兼容的浏览器范围，你可以在 `.browserslistrc` 文件里设置 [Browserslist](https://browsersl.ist/) 的值。
+
+当你创建一个新的 Modern.js 项目时，默认会包含一份 `.browserslistrc` 配置，这表示 JavaScript 代码会被编译至 ES6 格式。
+
+import DefaultBrowserslist from '@site-docs/components/default-browserslist';
+
+<DefaultBrowserslist />
+
+当项目中未指定 `overrideBrowserslist` 配置时，该 `.browserslistrc` 文件会默认生效。
+
+### 方式二：通过 package.json 配置
+
+你也可以在 `package.json` 文件中设置 `browserslist` 字段来配置 browserslist:
+
+```json title="package.json"
+{
+  "browserslist": [
+    "chrome >= 87"
+    // 其他浏览器的配置...
+  ]
+}
+```
+
+### 方式三：通过 `output.overrideBrowserslist` 配置
+
+你也可以在 `modern.config.js` 文件中设置 [`output.overrideBrowserslist`](/configure/app/output/override-browserslist) 字段来配置 browserslist:
+
+```js title="modern.config.js"
+export default {
+  output: {
+    overrideBrowserslist: [
+      'chrome >= 87',
+      // 其他浏览器的配置...
+    ],
+  },
+};
+```
+
+### 配置优先级
+
+`overrideBrowserslist` 配置的优先级高于项目中的 `.browserslistrc` 配置文件和 package.json 中的 `browserslist` 字段。
+
+大多数场景下，推荐优先使用 `.browserslistrc` 文件，而不是使用 `overrideBrowserslist` 配置。因为 `.browserslistrc` 文件是官方定义的配置文件，通用性更强，可以被社区中的其他库识别。
+
+:::tip
+请查看 [Rsbuild - 设置浏览器范围](https://v2.rsbuild.rs/zh/guide/advanced/browserslist) 来了解更多内容。
+:::
+
+import UpgradeBrowserslist from '@site-docs/components/upgrade-browserslist';
+
+<UpgradeBrowserslist />
+
+## Polyfill
+
+### 编译时 Polyfill
+
+Modern.js 在编译时默认通过 [core-js](https://github.com/zloirock/core-js) 引入对应的 Polyfill 代码。
+
+默认情况下会根据项目 Browserslist 的设置情况引入所需的 Polyfill 代码， 这样基本不用再担心项目源码和第三方依赖的 Polyfill 问题了，但是因为包含了一些没有用到的 Polyfill 代码，所以最终的包大小可能会有所增加。
+
+:::info
+对于明确第三方依赖不需要 Polyfill 的场景，可以设置 [`output.polyfill`](/configure/app/output/polyfill) 为 `usage`, 这样 Babel 编译时只会根据代码中使用到的语法引入 Polyfill 代码。
+
+:::
+
+import UAPolyfill from '@site-docs/components/ua-polyfill';
+
+<UAPolyfill />

package/docs/zh/guides/advanced-features/international/_meta.json

@@ -0,0 +1,10 @@
+[
+  "quick-start",
+  "configuration",
+  "locale-detection",
+  "resource-loading",
+  "routing",
+  "api",
+  "advanced",
+  "best-practices"
+]

package/docs/zh/guides/advanced-features/international/advanced.mdx

@@ -0,0 +1,132 @@
+---
+title: 高级用法
+---
+
+# 高级用法
+
+## SSR 场景
+
+SSR 场景下，插件在服务端检测语言、加载翻译资源，并将结果注入页面，客户端直接复用，避免语言闪烁。
+
+**完整配置：**
+
+```ts
+// modern.config.ts
+export default defineConfig({
+  server: {
+    ssr: true,
+  },
+  plugins: [
+    appTools(),
+    i18nPlugin({
+      localeDetection: {
+        localePathRedirect: true,
+        i18nextDetector: true,
+        languages: ['zh', 'en'],
+        fallbackLanguage: 'en',
+        detection: {
+          order: ['path', 'cookie', 'header'],
+          lookupHeader: 'accept-language',
+          caches: ['cookie'],
+        },
+      },
+      backend: {
+        loadPath: '/locales/{{lng}}/{{ns}}.json',
+      },
+    }),
+  ],
+});
+```
+
+服务端检测语言的优先级：URL 路径 → Cookie → `Accept-Language` 请求头 → `fallbackLanguage`。
+
+**路由配置（约定式路由）：**
+
+```
+routes/
+└── [lang]/
+    ├── layout.tsx
+    └── page.tsx
+```
+
+SSR 场景下，服务端检测到的语言会写入 `window._SSR_DATA`，客户端直接读取，不会再重新检测，确保两端语言一致。
+
+## 多入口配置
+
+不同入口可以使用不同的语言列表、检测方式和资源路径：
+
+```ts
+// modern.config.ts
+i18nPlugin({
+  localeDetection: {
+    // 全局默认配置
+    localePathRedirect: true,
+    languages: ['zh', 'en'],
+    fallbackLanguage: 'en',
+
+    // 按入口覆盖
+    localeDetectionByEntry: {
+      admin: {
+        localePathRedirect: false, // admin 入口不使用路径前缀
+        languages: ['en'],         // admin 只支持英文
+      },
+      mobile: {
+        languages: ['zh', 'en', 'ja'], // mobile 支持更多语言
+      },
+    },
+  },
+  backend: {
+    loadPath: '/locales/{{lng}}/{{ns}}.json', // 全局默认路径
+
+    // 按入口覆盖
+    backendOptionsByEntry: {
+      admin: {
+        loadPath: '/admin/locales/{{lng}}/{{ns}}.json',
+      },
+      mobile: {
+        loadPath: '/mobile/locales/{{lng}}/{{ns}}.json',
+      },
+    },
+  },
+});
+```
+
+## 自定义 i18next 实例
+
+默认情况下，插件会使用内部创建的 i18next 实例。如果需要对实例进行深度定制（如使用自定义插件、预配置选项），可以在运行时配置中传入自定义实例：
+
+```ts
+// src/i18n.ts
+import i18next from 'i18next';
+
+const customI18n = i18next.createInstance();
+// 可以在此 use() 自定义插件
+// customI18n.use(MyPlugin);
+
+export default customI18n;
+```
+
+```ts
+// src/modern.runtime.ts
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import customI18n from './i18n';
+
+export default defineRuntimeConfig({
+  i18n: {
+    i18nInstance: customI18n,
+    initOptions: {
+      fallbackLng: 'en',
+      supportedLngs: ['zh', 'en'],
+    },
+  },
+});
+```
+
+## 语言切换行为说明
+
+调用 `changeLanguage` 切换语言时：
+
+- **翻译更新**：所有使用 `t()` 的组件自动重新渲染，无需手动刷新
+- **URL 更新**（启用 `localePathRedirect` 时）：使用 `history.pushState` 更新 URL，不触发页面刷新，不影响浏览器前进/后退历史
+- **缓存更新**：根据 `caches` 配置写入 Cookie 或 LocalStorage，下次访问自动还原语言选择
+- **未启用路径前缀时**：只更新 i18next 实例和缓存，URL 不变