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

package/docs/zh/guides/advanced-features/low-level.mdx

@@ -6,14 +6,16 @@ sidebar_position: 10
 
 ## 使用方式
 
-Modern.js 内部默认集成了 [Babel](https://babeljs.io/)、[TypeScript](https://www.typescriptlang.org/)、[Webpack](https://webpack.js.org/)、[PostCSS](https://postcss.org/)、[Tailwind CSS](https://tailwindcss.com/) 等工具。通常情况下，默认配置能够满足大多业务开发需求。当有特殊需求时，可以通过底层配置来实现。
+Modern.js 内部默认集成了 [TypeScript](https://www.typescriptlang.org/)、[Rspack](https://rspack.rs/)、[PostCSS](https://postcss.org/)、[SWC](https://swc.rs/) 等工具。通常情况下，默认配置能够满足大多业务开发需求。当有特殊需求时，可以通过底层配置来实现。
 
-以配置 Webpack 为例，只需要在 `modern.config.ts` 中添加 [`tools.webpack`](/configure/app/tools/webpack) 即可：
+以配置 Rspack 为例，只需要在 `modern.config.ts` 中添加 [`tools.rspack`](/configure/app/tools/rspack) 即可：
 
 ```ts title="modern.config.ts"
 export default defineConfig({
   tools: {
-    webpack: config => {},
+    rspack: config => {
+      // 修改 Rspack 配置
+    },
   },
 });
 ```
@@ -28,16 +30,19 @@ export default defineConfig({
 
 目前提供的底层配置如下表：
 
-| 底层工具          | 配置                                                                  |
-| ----------------- | --------------------------------------------------------------------- |
-| DevServer         | [tools.devServer](/configure/app/tools/dev-server)               |
-| Babel             | [tools.babel](/configure/app/tools/babel)                        |
-| styled-components | [tools.styledComponents](/configure/app/tools/styled-components) |
-| PostCSS           | [tools.postcss](/configure/app/tools/postcss)                    |
-| Less              | [tools.less](/configure/app/tools/less)                          |
-| Sass              | [tools.sass](/configure/app/tools/sass)                          |
-| webpack           | [tools.webpack](/configure/app/tools/webpack)                    |
-| Minify CSS        | [tools.minifyCss](/configure/app/tools/minify-css)               |
-| terser            | [tools.terser](/configure/app/tools/terser)                      |
-| Tailwind CSS      | [tools.tailwind](/configure/app/tools/tailwindcss)               |
-| Autoprefixer      | [tools.autoprefixer](/configure/app/tools/autoprefixer)          |
+| 底层工具           | 配置                                                                 |
+| ------------------ | -------------------------------------------------------------------- |
+| Rspack             | [tools.rspack](/configure/app/tools/rspack)                          |
+| Bundler Chain      | [tools.bundlerChain](/configure/app/tools/bundler-chain)             |
+| SWC                | [tools.swc](/configure/app/tools/swc)                                |
+| TypeScript Checker | [tools.tsChecker](/configure/app/tools/ts-checker)                   |
+| PostCSS            | [tools.postcss](/configure/app/tools/postcss)                        |
+| Less               | [tools.less](/configure/app/tools/less)                              |
+| Sass               | [tools.sass](/configure/app/tools/sass)                              |
+| CSS Extract        | [tools.cssExtract](/configure/app/tools/css-extract)                 |
+| CSS Loader         | [tools.cssLoader](/configure/app/tools/css-loader)                   |
+| Style Loader       | [tools.styleLoader](/configure/app/tools/style-loader)               |
+| Lightning CSS      | [tools.lightningcssLoader](/configure/app/tools/lightningcss-loader) |
+| Minify CSS         | [tools.minifyCss](/configure/app/tools/minify-css)                   |
+| Autoprefixer       | [tools.autoprefixer](/configure/app/tools/autoprefixer)              |
+| HTML Plugin        | [tools.htmlPlugin](/configure/app/tools/html-plugin)                 |

package/docs/zh/guides/advanced-features/page-performance/code-split.mdx

@@ -7,7 +7,7 @@ sidebar_position: 3
 代码分割（code splitting）是优化前端资源加载的一种常用手段，本文将介绍 Modern.js 支持的三种代码分割方式：
 
 :::info
-使用 Modern.js [约定式路由](/guides/basic-features/routes#约定式路由)时，默认会根据路由组件做代码分割，无需自行进行代码分割。
+使用 Modern.js [约定式路由](/guides/basic-features/routes/routes#约定式路由)时，默认会根据路由组件做代码分割，无需自行进行代码分割。
 :::
 
 - 动态 `import`
@@ -16,7 +16,7 @@ sidebar_position: 3
 
 ## 动态 import
 
-使用动态 `import()` 语法，传入的 JS 模块将会被被打包到单独的 JS 文件中。例如：
+使用动态 `import()` 语法，传入的 JS 模块将会被打包到单独的 JS 文件中。例如：
 
 ```ts
 import('./math').then(math => {
@@ -29,7 +29,7 @@ import('./math').then(math => {
 React 官方提供的组件代码分割的方式。
 
 :::caution
-`React.lazy` 通常配合 `<Suspense>` 使用，因此仅在 CSR 或 React 18 Streaming SSR 中可用。
+`React.lazy` 通常配合 `<Suspense>` 使用，因此仅在 CSR 或 React 18+ 的 Streaming SSR 中可用。
 
 对于使用传统 SSR（字符串渲染）的项目，不支持 `React.lazy`，请使用 Loadable API。
 :::

package/docs/zh/guides/advanced-features/page-performance/inline-assets.mdx

@@ -101,12 +101,12 @@ import img from './foo.png?__inline=false';
 
 除了将静态资源文件内联到 JS 文件里，Modern.js 也支持将 JS 文件内联到 HTML 文件中。
 
-只需要开启 [output.enableInlineScripts](/configure/app/output/enable-inline-scripts) 配置项，构建生成的 JS 文件将不会被写入产物目录下，而是会直接内联到对应的 HTML 文件中。
+只需要开启 [output.inlineScripts](/configure/app/output/inline-scripts) 配置项，构建生成的 JS 文件将不会被写入产物目录下，而是会直接内联到对应的 HTML 文件中。
 
 ```ts
 export default {
   output: {
-    enableInlineScripts: true,
+    inlineScripts: true,
   },
 };
 ```
@@ -119,12 +119,12 @@ export default {
 
 你也可以将 CSS 文件内联到 HTML 文件中。
 
-只需要开启 [output.enableInlineStyles](/configure/app/output/enable-inline-styles) 配置项，构建生成的 CSS 文件将不会被写入产物目录下，而是会直接内联到对应的 HTML 文件中。
+只需要开启 [output.inlineStyles](/configure/app/output/inline-styles) 配置项，构建生成的 CSS 文件将不会被写入产物目录下，而是会直接内联到对应的 HTML 文件中。
 
 ```ts
 export default {
   output: {
-    enableInlineStyles: true,
+    inlineStyles: true,
   },
 };
 ```

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

@@ -40,26 +40,26 @@ npx yarn-deduplicate && yarn
 BUNDLE_ANALYZE=true pnpm build
 ```
 
-详见 [performance.bundleAnalyze](/configure/app/performance/bundle-analyze.html) 配置项。
+这将生成一个打包分析报告，帮助你识别体积较大的依赖。
 
 ## 提升 Browserslist 范围
 
 Modern.js 会根据项目的 Browserslist 配置范围进行代码编译，并注入相应的 Polyfill。如果项目不需要兼容旧版浏览器，可以根据实际情况来提升 Browserslist 范围，从而减少在语法和 Polyfill 上的编译开销。
 
-Modern.js 默认的 Browserslist 配置为：
+Modern.js 默认的 [`output.overrideBrowserslist`](/configure/app/output/override-browserslist.html) 配置为：
 
 ```js
-['> 0.01%', 'not dead', 'not op_mini all'];
+['chrome >= 87', 'edge >= 88', 'firefox >= 78', 'safari >= 14'];
 ```
 
-比如只兼容 Chrome 61 以上的浏览器，可以改成：
+比如只兼容 Chrome 100 以上的浏览器，可以改成：
 
 ```js
-['Chrome >= 61'];
+['Chrome >= 100'];
 ```
 
 :::tip
-请阅读 [设置浏览器范围](https://rsbuild.rs/zh/guide/advanced/browserslist) 章节来了解更多关于 Browserslist 的用法。
+请阅读 [Browserslist 配置](/guides/advanced-features/compatibility.html) 章节来了解更多关于 Browserslist 的用法。
 :::
 
 ## 按需引入 polyfill
@@ -98,23 +98,9 @@ export default {
 
 良好的拆包策略对于提升应用的加载性能是十分重要的，可以充分利用浏览器的缓存机制，减少请求数量，加快页面加载速度。
 
-Modern.js 提供了与 Rsbuild 相同的[拆包策略](https://rsbuild.rs/zh/guide/optimization/code-splitting)，但在默认策略 `split-by-experience` 上有些许差异。
+在 Modern.js 中内置了[多种拆包策略](https://rsbuild.rs/zh/guide/optimization/split-chunk)，可以满足大部分应用的需求，你也可以根据自己的业务场景，自定义拆包配置。
 
-当项目中安装了 `antd`、`@arco-design/web-react` 或 `@douyinfe/semi-ui` 包时，会自动添加对应的分组。具体实现参考：
-
-```ts
-if (isPackageInstalled('antd', rootPath)) {
-  groups.antd = ['antd'];
-}
-if (isPackageInstalled('@arco-design/web-react', rootPath)) {
-  groups.arco = [/@?arco-design/];
-}
-if (isPackageInstalled('@douyinfe/semi-ui', rootPath)) {
-  groups.semi = [/@(ies|douyinfe)[\\/]semi-.*/];
-}
-```
-
-内置的策略可以满足大部分应用的需求，你也可以根据自己的业务场景，自定义拆包配置。比如将 node_modules 下的 `axios` 库拆分到 `axios.js` 中：
+比如将 node_modules 下的 `axios` 库拆分到 `axios.js` 中：
 
 ```js
 export default {

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 插件：
 
@@ -18,26 +32,19 @@ React Compiler 是 React 19 引入的一个实验性编译器，它可以自动
 import { appTools, defineConfig } from '@modern-js/app-tools';
 
 export default defineConfig({
-  runtime: {
-    router: true,
-  },
   tools: {
     babel(_, { addPlugins }) {
       addPlugins([
         [
           'babel-plugin-react-compiler',
           {
-            target: '18',
+            target: '18', // 或 '17'，根据你使用的 React 版本
           },
         ],
       ]);
     },
   },
-  plugins: [
-    appTools({
-      bundler: 'rspack',
-    }),
-  ],
+  plugins: [appTools()],
 });
 ```
 

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

@@ -17,11 +17,7 @@ Modern.js 也保留了旧版本中使用 `useLoader` 获取数据时的 SSR 日
 | 阶段          | 消息                                         | Level |
 | ------------- | -------------------------------------------- | ----- |
 | PRERENDER   | App Prerender                          | error |
-| USE_LOADER | App run useLoader         | error |
 
-:::tip
-`useLoader` API 目前已经废弃，建议迁移到约定式路由并使用 Data Loader 进行数据获取。已经使用 Data Loader 的应用，可以开启 [`ssr.disablePrerender`](/configure/app/server/ssr.html#object-类型)，禁止预渲染，提升 SSR 性能。
-:::
 
 ## 内置 Monitor
 

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

@@ -56,11 +56,11 @@ export interface Monitors {
   warn(message: string, ...args: any[]): void;
   debug(message: string, ...args: any[]): void;
   info(message: string, ...args: any[]): void;
-  trace(message: string,...args: any[]): void;
+  trace(message: string, ...args: any[]): void;
 
   // 指标事件
   timing(name: string, dur: number, ...args: any[]): void;
-  counter(name: string, ...args: any[]): void
+  counter(name: string, ...args: any[]): void;
 }
 ```
 
@@ -71,31 +71,102 @@ Modern.js 内置了默认的 Monitor，不同的事件会触发内置 Monitor
 - [日志事件](/guides/advanced-features/server-monitor/logger)
 - [指标事件](/guides/advanced-features/server-monitor/metrics)
 
-
 ## 注册 Monitors
 
-开发者可以通过 Monitors 的 `push` API 注册自己的 Monitor，但只能在[服务端中间件](/apis/app/runtime/web-server/unstable_middleware)或服务端插件中注册，在 Data Loader、组件、init 函数中无法注册。
+开发者可以通过 Monitors 的 `push` API 注册自己的 Monitor，但只能在[服务端中间件](/guides/advanced-features/web-server#unstable-middleware)或[服务端插件](/plugin/server-plugins/api)中注册，在 Data Loader、组件、init 函数中无法注册。
 
-:::note
-目前暂未开放服务端插件，后续会补充相关文档。
-:::
+```ts title="server/modern.server.ts"
+import {
+  defineServerConfig,
+  type MiddlewareHandler,
+} from '@modern-js/server-runtime';
+import type { MonitorEvent } from '@modern-js/types';
 
-```ts title="server/index.ts"
-import type { CoreMonitors } from '@modern-js/types';
-const injectMonitorMiddleware = (c) => {
-    const monitors = c.get('monitors');
-    const myMonitor = (event: MonitorEvent) => {
+const injectMonitorMiddleware: MiddlewareHandler = async (c, next) => {
+  const monitors = c.get('monitors');
+  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}`);
+    }
+  };
+  monitors.push(myMonitor);
+  await next();
+};
+
+export default defineServerConfig({
+  middlewares: [
+    {
+      name: 'inject-monitor',
+      handler: injectMonitorMiddleware,
+    },
+  ],
+});
+```
+
+在服务端插件中注册 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') {
-          // some code
-        } else {
-          // some other code
+          // 处理日志事件
+          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}`);
         }
-    }
-    monitors.push(myMonitor);
-    return next();
-}
+      };
+
+      // 使用标志确保 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 const middlewares = [injectMonitorMiddleware]
+export default defineServerConfig({
+  plugins: [myMonitorPlugin()],
+});
 ```
 
 ## 调用 Monitors
@@ -109,7 +180,7 @@ Modern.js 允许开发者在 Data Loader、组件中调用 Monitors。
 在 Data Loader 中，开发者可以这样使用：
 
 ```ts title="routes/page.data.ts"
-import { LoaderFunctionArgs } from '@modern-js/runtime/router';
+import type { LoaderFunctionArgs } from '@modern-js/runtime/router';
 import { getMonitors } from '@modern-js/runtime';
 const loader = async ({ context }: LoaderFunctionArgs) => {
     const monitors = getMonitors();
@@ -126,32 +197,44 @@ const loader = async ({ context }: LoaderFunctionArgs) => {
 在组件中调用 Monitors，需要判断当前运行环境是否为 Node.js：
 
 ```tsx title="routes/page.tsx"
-import { getMonitors } from '@modern-js/runtime';
+import { use } from 'react';
+import { RuntimeContext, getMonitors } from '@modern-js/runtime';
 const Page = () => {
-    const { context } = useRuntimeContext();
-    if (process.env.MODERN_TARGET === 'node') {
-        const monitors = getMonitors();
-        monitors.info();
-    }
-    return <div>Hello World</div>
-}
+  const context = use(RuntimeContext);
+  if (process.env.MODERN_TARGET === 'node') {
+    const monitors = getMonitors();
+    monitors.info('Page rendered');
+  }
+  return <div>Hello World</div>;
+};
 export default Page;
 ```
 
 在中间件中，我们也可以调用 Monitors，但方式与在运行时代码中不同，需要通过 `context` 来获取：
 
-```ts title="server/index.ts"
-import { UnstableMiddleware } from '@modern-js/runtime/server';
+```ts title="server/modern.server.ts"
+import {
+  defineServerConfig,
+  type MiddlewareHandler,
+} from '@modern-js/server-runtime';
 
-const time: UnstableMiddleware = async (c, next) => {
+export const handler: MiddlewareHandler = async (c, next) => {
+  const monitors = c.get('monitors');
   const start = Date.now();
+
   await next();
+
   const end = Date.now();
-  const monitors = c.get('monitors');
-  monitors.info(`${end - start}`);
+  // 上报耗时
+  monitors.timing('request_timing', end - start);
 };
 
-export const unstableMiddleware: UnstableMiddleware[] = [time];
+export default defineServerConfig({
+  middlewares: [
+    {
+      name: 'request-timing',
+      handler,
+    },
+  ],
+});
 ```
-
-