@modern-js/main-doc 3.0.0-alpha.0 → 3.0.0-alpha.1

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

@@ -335,29 +335,20 @@ export default defineRuntimeConfig({
 
 ### i18nInstance 配置
 
-如果需要使用自定义的 i18next 实例，可以在运行时配置中提供：
+如果需要使用自定义的 i18n 实例，可以在运行时配置中提供：
 
-```ts
-import { defineRuntimeConfig } from '@modern-js/runtime';
-import i18next from 'i18next';
+import CustomInstanceCode from '@site-docs/components/international/custom-instance-code';
 
-// 创建自定义实例
-const customI18n = i18next.createInstance({
-  // 自定义配置
-});
-
-export default defineRuntimeConfig({
-  i18n: {
-    i18nInstance: customI18n,
-  },
-});
-```
+<CustomInstanceCode />
 
 ### initOptions 配置
 
-`initOptions` 会传递给 i18next 的 `init` 方法，支持所有 i18next 配置选项：
+import InitOptionsDesc from '@site-docs/components/international/init-options-desc';
+
+<InitOptionsDesc />
 
 :::info
+
 如果启用了 `localePathRedirect`，`detection` 配置应该在 CLI 配置中设置，而不是在 `initOptions` 中。这是因为服务端插件需要读取 CLI 配置中的 `detection` 选项来进行语言检测和路径重定向。
 :::
 

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

@@ -51,32 +51,9 @@ export default defineConfig({
 
 ### 在 `src/modern.runtime.ts` 中配置运行时选项
 
-创建 `src/modern.runtime.ts` 文件并配置 i18n 运行时选项：
+import InstanceCode from '@site-docs/components/international/instance-code';
 
-```ts
-import { defineRuntimeConfig } from '@modern-js/runtime';
-import i18next from 'i18next';
-
-// 建议创建一个新的 i18next 实例，避免使用全局默认实例
-const i18nInstance = i18next.createInstance();
-
-export default defineRuntimeConfig({
-  i18n: {
-    i18nInstance: i18nInstance,
-    initOptions: {
-      fallbackLng: 'en',
-      supportedLngs: ['zh', 'en'],
-    },
-  },
-});
-```
-
-:::info
-`modern.runtime.ts` 是运行时配置文件，用于配置 i18next 的初始化选项。即使是最基础的配置，也建议创建此文件以确保插件正常工作。
-
-建议使用 `i18next.createInstance()` 创建一个新的实例，而不是直接使用默认导出的 `i18next`，这样可以避免全局状态污染，并确保每个应用都有独立的 i18n 实例。
-
-:::
+<InstanceCode />
 
 ### 创建语言资源文件
 

package/docs/zh/guides/advanced-features/page-performance/optimize-bundle.mdx

@@ -40,7 +40,7 @@ npx yarn-deduplicate && yarn
 BUNDLE_ANALYZE=true pnpm build
 ```
 
-详见 [performance.bundleAnalyze](/configure/app/performance/bundle-analyze.html) 配置项。
+这将生成一个打包分析报告，帮助你识别体积较大的依赖。
 
 ## 提升 Browserslist 范围
 

package/docs/zh/guides/advanced-features/page-performance/react-compiler.mdx

@@ -6,11 +6,25 @@ React Compiler 是 React 19 引入的一个实验性编译器，它可以自动
 
 ## 如何使用
 
-在 Modern.js 中使用 React Compiler 的步骤如下：
+### React 19
 
-1. Modern.js 目前项目还未正式支持 React 19，可以在 React 17 或 18 项目中安装 `react-compiler-runtime@rc`，以允许编译后的代码在 19 之前的版本上运行。
+如果你使用的是 React 19，Modern.js 已内置支持 React Compiler，无需额外配置即可使用。
 
-2. 目前 React Compiler 仅提供了 Babel 插件，你需要安装 `babel-plugin-react-compiler`。
+### React 17 或 18
+
+如果你使用的是 React 17 或 18，需要按照以下步骤配置：
+
+1. 安装 `react-compiler-runtime`，以允许编译后的代码在 19 之前的版本上运行：
+
+```bash
+npm install react-compiler-runtime
+```
+
+2. 安装 `babel-plugin-react-compiler`：
+
+```bash
+npm install babel-plugin-react-compiler
+```
 
 3. 在你的 Modern.js 配置文件中注册 Babel 插件：
 
@@ -24,7 +38,7 @@ export default defineConfig({
         [
           'babel-plugin-react-compiler',
           {
-            target: '18',
+            target: '18', // 或 '17'，根据你使用的 React 版本
           },
         ],
       ]);

package/docs/zh/guides/advanced-features/server-monitor/monitors.mdx

@@ -73,11 +73,7 @@ Modern.js 内置了默认的 Monitor，不同的事件会触发内置 Monitor
 
 ## 注册 Monitors
 
-开发者可以通过 Monitors 的 `push` API 注册自己的 Monitor，但只能在[服务端中间件](/guides/advanced-features/web-server#unstable-middleware)或服务端插件中注册，在 Data Loader、组件、init 函数中无法注册。
-
-:::note
-目前暂未开放服务端插件，后续会补充相关文档。
-:::
+开发者可以通过 Monitors 的 `push` API 注册自己的 Monitor，但只能在[服务端中间件](/guides/advanced-features/web-server#unstable-middleware)或[服务端插件](/plugin/server-plugins/api)中注册，在 Data Loader、组件、init 函数中无法注册。
 
 ```ts title="server/modern.server.ts"
 import {
@@ -114,6 +110,65 @@ export default defineServerConfig({
 });
 ```
 
+在服务端插件中注册 Monitor：
+
+```ts title="server/plugins/my-monitor-plugin.ts"
+import type { ServerPlugin } from '@modern-js/server-runtime';
+import type { MonitorEvent } from '@modern-js/types';
+
+const myMonitorPlugin = (): ServerPlugin => ({
+  name: '@my-org/my-monitor-plugin',
+  setup(api) {
+    api.onPrepare(() => {
+      const { middlewares } = api.getServerContext();
+
+      // 定义 monitor，确保只创建一次
+      const myMonitor = (event: MonitorEvent) => {
+        if (event.type === 'log') {
+          // 处理日志事件
+          console.log(`[${event.payload.level}] ${event.payload.message}`);
+        } else if (event.type === 'timing') {
+          // 处理性能指标事件
+          console.log(`Timing: ${event.payload.name} = ${event.payload.dur}ms`);
+        } else if (event.type === 'counter') {
+          // 处理计数事件
+          console.log(`Counter: ${event.payload.name}`);
+        }
+      };
+
+      // 使用标志确保 monitor 只注册一次
+      let monitorRegistered = false;
+
+      middlewares.push({
+        name: 'inject-monitor',
+        handler: async (c, next) => {
+          const monitors = c.get('monitors');
+          // 只在第一次请求时注册 monitor
+          if (!monitorRegistered) {
+            monitors.push(myMonitor);
+            monitorRegistered = true;
+          }
+          await next();
+        },
+      });
+    });
+  },
+});
+
+export default myMonitorPlugin;
+```
+
+然后在 `server/modern.server.ts` 中配置插件：
+
+```ts title="server/modern.server.ts"
+import { defineServerConfig } from '@modern-js/server-runtime';
+import myMonitorPlugin from './plugins/my-monitor-plugin';
+
+export default defineServerConfig({
+  plugins: [myMonitorPlugin()],
+});
+```
+
 ## 调用 Monitors
 
 Modern.js 允许开发者在 Data Loader、组件中调用 Monitors。

package/docs/zh/guides/basic-features/data/data-cache.mdx

@@ -2,14 +2,11 @@
 title: 数据缓存
 sidebar_position: 4
 ---
+
 # 数据缓存
 
 `cache` 函数可以让你缓存数据获取或计算的结果，相比整页[渲染缓存](/guides/basic-features/render/ssr-cache)，它提供了更精细的数据粒度控制，并且适用于客户端渲染(CSR)、服务端渲染（SSR）、API 服务(BFF)等多种场景。
 
-:::info
-需要 x.65.5 及以上版本
-:::
-
 ## 基本用法
 
 :::note
@@ -79,7 +76,6 @@ Modern.js 提供的 `cache` 函数可以在任意的前端或服务端的代码
 无 `options` 参数时，可以看作是 react [`cache`](https://react.dev/reference/react/cache) 函数的替代品，可以在任意服务端代码中使用（比如可以在 SSR 项目的 data loader 中），不局限于 server component。
 :::
 
-
 ```ts
 import { cache } from '@modern-js/runtime/cache';
 import { fetchUserData } from './api';
@@ -108,8 +104,8 @@ const getDashboardStats = cache(
     return await fetchComplexStatistics();
   },
   {
-    maxAge: CacheTime.MINUTE * 2,  // 在 2 分钟内调用该函数会返回缓存的数据
-  }
+    maxAge: CacheTime.MINUTE * 2, // 在 2 分钟内调用该函数会返回缓存的数据
+  },
 );
 ```
 
@@ -133,7 +129,7 @@ const getDashboardStats = cache(
   {
     maxAge: CacheTime.MINUTE * 2,
     revalidate: CacheTime.MINUTE * 1,
-  }
+  },
 );
 ```
 
@@ -150,7 +146,7 @@ const getDashboardStats = cache(
   },
   {
     tag: 'dashboard',
-  }
+  },
 );
 
 const getComplexStatistics = cache(
@@ -159,7 +155,7 @@ const getComplexStatistics = cache(
   },
   {
     tag: 'dashboard',
-  }
+  },
 );
 
 await revalidateTag('dashboard'); // 会使 getDashboardStats 函数和 getComplexStatistics 函数的缓存都失效
@@ -184,7 +180,7 @@ const getUser = cache(
     maxAge: CacheTime.MINUTE * 5,
     // 只使用第一个参数（userId）作为缓存键
     getKey: (userId, options) => userId,
-  }
+  },
 );
 
 // 下面两次调用会共享缓存，因为 getKey 只使用了 userId
@@ -214,11 +210,10 @@ const getUser = cache(
   {
     maxAge: CacheTime.MINUTE * 5,
     getKey: (userId, options) => generateKey(userId),
-  }
+  },
 );
 ```
 
-
 #### `customKey` 参数
 
 `customKey` 参数用于**完全定制**缓存的键，它是一个函数，接收一个包含以下属性的对象，返回值必须是字符串类型。
@@ -232,6 +227,7 @@ const getUser = cache(
 :::info
 
 一般在以下场景，缓存会失效：
+
 1. 函数的入参发生变化
 2. 不满足 maxAge 条件
 3. 调用了 `revalidateTag`
@@ -247,16 +243,13 @@ import { cache } from '@modern-js/runtime/cache';
 import { fetchUserData } from './api';
 
 // 不同的函数引用，但是通过 customKey 可以使它们共享一个缓存
-const getUserA = cache(
-  fetchUserData,
-  {
-    maxAge: CacheTime.MINUTE * 5,
-    customKey: ({ params }) => {
-      // 返回一个稳定的字符串作为缓存的键
-      return `user-${params[0]}`;
-    },
-  }
-);
+const getUserA = cache(fetchUserData, {
+  maxAge: CacheTime.MINUTE * 5,
+  customKey: ({ params }) => {
+    // 返回一个稳定的字符串作为缓存的键
+    return `user-${params[0]}`;
+  },
+});
 
 // 即使函数引用变了，只要 customKey 返回相同的值，也会命中缓存
 const getUserB = cache(
@@ -267,7 +260,7 @@ const getUserB = cache(
       // 返回与 getUserA 相同的键
       return `user-${params[0]}`;
     },
-  }
+  },
 );
 
 // 现在你可以在不同的函数实现间共享缓存
@@ -275,12 +268,9 @@ await getUserA(123); // 获取数据并使用键 "user-123" 缓存
 await getUserB(123); // 缓存命中，返回缓存的数据
 
 // 可以利用 generatedKey 参数在默认键的基础上进行修改
-const getUserC = cache(
-  fetchUserData,
-  {
-    customKey: ({ generatedKey }) => `prefix-${generatedKey}`,
-  }
-);
+const getUserC = cache(fetchUserData, {
+  customKey: ({ generatedKey }) => `prefix-${generatedKey}`,
+});
 
 // 用于可预测的缓存键，便于外部管理
 const getUserD = cache(
@@ -290,7 +280,7 @@ const getUserD = cache(
   {
     maxAge: CacheTime.MINUTE * 5,
     customKey: ({ params }) => `app:user:${params[0]}`,
-  }
+  },
 );
 ```
 
@@ -307,30 +297,31 @@ const stats = {
   hits: 0,
   misses: 0,
   stales: 0,
-  hitRate: () => stats.hits / stats.total
+  hitRate: () => stats.hits / stats.total,
 };
 
-const getUser = cache(
-  fetchUserData,
-  {
-    maxAge: CacheTime.MINUTE * 5,
-    onCache({ status, key, params, result }) {
-      // status 可以是 'hit'、'miss' 或 'stale'
-      stats.total++;
-
-      if (status === 'hit') {
-        stats.hits++;
-      } else if (status === 'miss') {
-        stats.misses++;
-      } else if (status === 'stale') {
-        stats.stales++;
-      }
-
-      console.log(`缓存${status === 'hit' ? '命中' : status === 'miss' ? '未命中' : '陈旧'}，键：${String(key)}`);
-      console.log(`当前命中率：${stats.hitRate() * 100}%`);
+const getUser = cache(fetchUserData, {
+  maxAge: CacheTime.MINUTE * 5,
+  onCache({ status, key, params, result }) {
+    // status 可以是 'hit'、'miss' 或 'stale'
+    stats.total++;
+
+    if (status === 'hit') {
+      stats.hits++;
+    } else if (status === 'miss') {
+      stats.misses++;
+    } else if (status === 'stale') {
+      stats.stales++;
     }
-  }
-);
+
+    console.log(
+      `缓存${
+        status === 'hit' ? '命中' : status === 'miss' ? '未命中' : '陈旧'
+      }，键：${String(key)}`,
+    );
+    console.log(`当前命中率：${stats.hitRate() * 100}%`);
+  },
+});
 
 // 使用示例
 await getUser(1); // 缓存未命中
@@ -351,6 +342,7 @@ await getUser(2); // 缓存未命中
 这个回调只在提供 `options` 参数时被调用。当使用无 options 的缓存函数时，不会调用 `onCache` 回调。
 
 `onCache` 回调对以下场景非常有用：
+
 - 监控缓存性能
 - 计算命中率
 - 记录缓存操作
@@ -408,11 +400,13 @@ configureCache({
 ##### 使用 `customKey` 确保缓存键稳定性
 
 :::warning 重要建议
+
 当使用自定义存储容器（如 Redis）时，**建议配置 `customKey`** 来确保缓存键的稳定性。这样可以确保：
 
 1. **跨进程共享**：不同服务器实例能够共享相同的缓存
 2. **应用重启后缓存有效**：重启应用后仍能命中之前的缓存
 3. **代码部署后缓存保持**：代码更新后相同逻辑的缓存仍然有效
+
 :::
 
 默认的缓存键生成机制基于函数引用，在分布式环境中可能不够稳定。建议使用 `customKey` 提供稳定的缓存键：
@@ -434,7 +428,7 @@ const getUser = cache(
     maxAge: CacheTime.MINUTE * 5,
     // 使用被缓存函数相关的稳定标识符作为缓存键
     customKey: () => `fetchUserData`,
-  }
+  },
 );
 ```
 
@@ -502,4 +496,3 @@ configureCache({
 1. **序列化**：所有的缓存数据都会被序列化为字符串存储，容器只需要处理字符串的存取操作。
 
 2. **TTL 支持**：如果你的存储后端支持 TTL（生存时间），可以在 `set` 方法中使用 `options.ttl` 参数（单位为秒）。
-

package/docs/zh/guides/basic-features/data/data-fetch.mdx

@@ -9,10 +9,6 @@ Modern.js 中提供了开箱即用的数据获取能力，开发者可以通过
 
 ## 什么是 Data Loader
 
-:::note
-Modern.js v1 项目通过 `useLoader` 获取数据，这已经不是我们推荐的用法，建议迁移到 Data Loader。
-:::
-
 Modern.js 推荐使用[约定式路由](/guides/basic-features/routes/routes)做路由的管理，每个路由组件（`layout.ts`，`page.ts` 或 `$.tsx`）都可以有一个同名的 `.data` 文件。这些文件可以导出一个 `loader` 函数，我们称为 Data Loader，它会在对应的路由组件渲染之前执行，为组件提供数据。如下面示例：
 
 ```bash
@@ -40,17 +36,19 @@ export const loader = async (): Promise<ProfileData> => {
 ```
 
 :::warning 兼容性
+
 - 在之前的版本中，Data Loader 是定义在 `.loader` 文件中的。当前版本中，我们推荐定义在 `.data` 文件中，同时我们会保持对 `.loader` 文件的兼容。
 - 在 `.loader` 文件中，Data Loader 可以默认导出。但在 `data` 文件中，Data Loader 需要以 `loader` 具名导出。
+
 ```ts
-  // xxx.loader.ts
-export default () => {}
+// xxx.loader.ts
+export default () => {};
 
 // xxx.data.ts
-export const loader = () => {}
+export const loader = () => {};
 ```
-:::
 
+:::
 
 在路由组件中，你可以通过 `useLoaderData` 函数获取数据：
 
@@ -162,8 +160,8 @@ export async function loader() {
   const res = await fetch('URL_ADDRESS');
   const data = await res.json();
   return {
-    message: data.message
-  }
+    message: data.message,
+  };
 }
 ```
 
@@ -208,7 +206,7 @@ export default ErrorBoundary;
 // routes/user/profile/page.data.ts
 export async function loader() {
   const user = await fetchUser();
-  if(!user){
+  if (!user) {
     throw new Response('The user was not found', { status: 404 });
   }
   return user;
@@ -261,7 +259,6 @@ export function UserLayout() {
 
 如果想获取 `entry1/routes/layout.tsx` 中 `loader` 返回的数据，`routeId` 的值就是 `entry1_layout`。
 
-
 ## Loading UI (Experimental)
 
 :::info Experimental

package/docs/zh/guides/basic-features/debug/proxy.mdx

@@ -4,19 +4,16 @@ sidebar_position: 6
 
 # 网络代理
 
-Modern.js 在 [`tools.devServer`](/configure/app/tools/dev-server) 中提供了配置开发环境代理的方式。例如，将本地开发接口，代理到线上某个地址：
+Modern.js 在 [`dev.server.proxy`](/configure/app/dev/server) 中提供了配置开发环境代理的方式。例如，将本地开发接口，代理到线上某个地址：
 
 ```ts title="modern.config.ts"
 import { defineConfig } from '@modern-js/app-tools';
 
 export default defineConfig({
-  tools: {
-    devServer: {
+  dev: {
+    server: {
       proxy: {
-        '/go/api': {
-          target: 'http://www.example.com/',
-          changeOrigin: true,
-        },
+        '/go/api': 'http://www.example.com/',
       },
     },
   },