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

package/docs/zh/plugin/plugin-system.mdx

@@ -6,15 +6,13 @@ Modern.js 采用高度可扩展的插件化架构，其核心功能和扩展能
 
 Modern.js 秉承“一切皆插件”的设计哲学，将框架的各项功能模块化，通过插件的形式进行组装和扩展。这种设计带来了诸多优势，包括：
 
--   **高内聚，低耦合**：各功能模块独立开发、测试和维护，降低系统复杂度。
--   **灵活可扩展**：用户可通过编写或组合插件，轻松定制框架行为，无需修改核心代码。
--   **易于复用**：插件可跨项目共享，提高开发效率。
--   **渐进式增强**：按需引入插件，无需一开始就承载所有功能的复杂性。
+- **高内聚，低耦合**：各功能模块独立开发、测试和维护，降低系统复杂度。
+- **灵活可扩展**：用户可通过编写或组合插件，轻松定制框架行为，无需修改核心代码。
+- **易于复用**：插件可跨项目共享，提高开发效率。
+- **渐进式增强**：按需引入插件，无需一开始就承载所有功能的复杂性。
 
 ## 插件类型与适用场景
 
-Modern.js 提供了三种主要插件类型，分别对应应用开发的不同阶段：
-
 **CLI 插件**：
     -   **作用阶段**：构建时（执行 `modern` 命令时）。
     -   **典型场景**：
@@ -47,15 +45,15 @@ Modern.js 提供了三种主要插件类型，分别对应应用开发的不同
 一个典型的 Modern.js 插件包含以下几个关键部分：
 
 ```ts
-import type { Plugin } from '@modern-js/plugin-v2';
+import type { Plugin } from '@modern-js/plugin';
 
 const myPlugin: Plugin = {
   name: 'my-awesome-plugin', // 插件的唯一标识符（必需）
 
   // 插件依赖和执行顺序（可选）
-  pre: [],    // 在此插件之前执行的插件名列表，默认为空数组
-  post: [],   // 在此插件之后执行的插件名列表，默认为空数组
-  required: [],// 必需的插件列表，若依赖的插件未注册，则会报错，默认为空数组
+  pre: [], // 在此插件之前执行的插件名列表，默认为空数组
+  post: [], // 在此插件之后执行的插件名列表，默认为空数组
+  required: [], // 必需的插件列表，若依赖的插件未注册，则会报错，默认为空数组
   usePlugins: [], // 内部使用的插件实例列表，默认为空数组
 
   // 注册新的 Hook (可选)
@@ -64,8 +62,12 @@ const myPlugin: Plugin = {
   // 插件的入口函数（必需）
   setup(api) {
     // 插件的核心逻辑，通过 api 对象调用插件 API
-    api.modifyWebpackConfig(config => { /* ... */ });
-    api.onPrepare(() => { /* ... */ });
+    api.modifyWebpackConfig(config => {
+      /* ... */
+    });
+    api.onPrepare(() => {
+      /* ... */
+    });
     // ... 其他 API 调用
   },
 };
@@ -129,98 +131,99 @@ export default myPlugin;
 - 类型： `Record<string, PluginHook<(...args: any[]) => any>>`
 - 说明：扩展当前支持的 Hook 函数，以实现自定义功能。
 
-
 ## 插件 Hook 模型
 
 Modern.js 插件系统的核心是其 Hook 模型，它定义了插件之间的通信机制。Modern.js 主要提供两种 Hook 类型：
 
 ### Async Hook（异步 Hook）
 
--   **特点**：
-    -   Hook 函数异步执行，支持 `async/await`。
-    -   前一个 Hook 函数的返回值会作为下一个 Hook 函数的第一个参数。
-    -   最终返回最后一个 Hook 函数的返回值。
--   **适用场景**：涉及异步操作的场景（如网络请求、文件读写等）。
--   **创建方式**：使用 `createAsyncHook` 创建。
+- **特点**：
+  - Hook 函数异步执行，支持 `async/await`。
+  - 前一个 Hook 函数的返回值会作为下一个 Hook 函数的第一个参数。
+  - 最终返回最后一个 Hook 函数的返回值。
+- **适用场景**：涉及异步操作的场景（如网络请求、文件读写等）。
+- **创建方式**：使用 `createAsyncHook` 创建。
 
 示例：
 
 ```ts
 // 定义 Hooks
-import { createAsyncHook } from '@modern-js/plugin-v2';
+import { createAsyncHook } from '@modern-js/plugin';
 
 export type AfterPrepareFn = () => Promise<void> | void;
 export const onAfterPrepare = createAsyncHook<AfterPrepareFn>();
 
 // 插件中注册 Hooks
 const myPlugin = () => ({
-  name: "my-plugin",
+  name: 'my-plugin',
   registryHooks: {
     onAfterPrepare,
   },
-  setup: (api) => {
+  setup: api => {
     api.onPrepare(async () => {
       // 插件中使用注册的 Hooks
       const hooks = api.getHooks();
       await hooks.onAfterPrepare.call();
     });
-  }
+  },
 });
 
 // 在其他插件中使用 Hook
 const myPlugin2 = () => ({
-  name: "my-plugin-2",
-  setup: (api) => {
+  name: 'my-plugin-2',
+  setup: api => {
     api.onAfterPrepare(async () => {
       // TOOD
     });
-  }
-})
+  },
+});
 ```
 
 ### Sync Hook（同步 Hook）
 
--   **特点**：
-    -   Hook 函数同步执行。
-    -   前一个 Hook 函数的返回值会作为下一个 Hook 函数的第一个参数。
-    -   最终返回最后一个 Hook 函数的返回值。
--   **适用场景**：需要同步修改数据的场景（如修改配置、路由等）。
--   **创建方式**：使用 `createSyncHook` 创建。
+- **特点**：
+  - Hook 函数同步执行。
+  - 前一个 Hook 函数的返回值会作为下一个 Hook 函数的第一个参数。
+  - 最终返回最后一个 Hook 函数的返回值。
+- **适用场景**：需要同步修改数据的场景（如修改配置、路由等）。
+- **创建方式**：使用 `createSyncHook` 创建。
 
 示例：
 
 ```ts
 // 定义 Hooks
-import { createSyncHook } from '@modern-js/plugin-v2';
+import { createSyncHook } from '@modern-js/plugin';
 
-type RouteObject = {/** TODO **/};
+type RouteObject = {
+  /** TODO **/
+};
 const modifyRoutes = createSyncHook<(routes: RouteObject[]) => RouteObject[]>();
 
 // 插件中注册 Hooks
 const myPlugin = () => ({
-  name: "my-plugin",
+  name: 'my-plugin',
   registryHooks: {
     modifyRoutes,
   },
-  setup: (api) => {
+  setup: api => {
     api.onPrepare(async () => {
       const routes = {};
       // 在插件中使用注册的 Hooks
       const hooks = api.getHooks();
       const routesResult = hooks.modifyRoutes.call(routes);
     });
-  }
+  },
 });
 
 // 其他插件使用 Hooks
 const myPlugin2 = () => ({
-  name: "my-plugin",
-  setup: (api) => {
-    api.modifyRoutes(async (routes) => {
+  name: 'my-plugin',
+  setup: api => {
+    api.modifyRoutes(async routes => {
       // 修改 routes
       return routes;
     });
-  }
+  },
 });
 ```
 

package/docs/zh/plugin/runtime-plugins/api.mdx

@@ -13,18 +13,18 @@ Runtime 插件需要通过 `src/modern.runtime.ts` 中的 [`plugins`](/configure
 一个典型的 Runtime 插件如下所示：
 
 ```ts
-import type { RuntimePluginFuture } from '@modern-js/runtime';
+import type { RuntimePlugin } from '@modern-js/runtime';
 
-const myRuntimePlugin = (): RuntimePluginFuture => ({
+const myRuntimePlugin = (): RuntimePlugin => ({
   name: 'my-runtime-plugin',
-  setup: (api) => {
+  setup: api => {
     // 使用 api 注册钩子
-    api.onBeforeRender((context) => {
+    api.onBeforeRender(context => {
       console.log('Before rendering:', context);
     });
 
-    api.wrapRoot((App) => {
-      return (props) => (
+    api.wrapRoot(App => {
+      return props => (
         <MyContextProvider>
           <App {...props} />
         </MyContextProvider>
@@ -34,18 +34,17 @@ const myRuntimePlugin = (): RuntimePluginFuture => ({
 });
 
 export default myRuntimePlugin;
-
 ```
 
--   `name`： 插件的唯一标识符。
--   `setup`： 插件的主要逻辑，接收一个 `api` 对象作为参数，用于注册钩子。
+- `name`： 插件的唯一标识符。
+- `setup`： 插件的主要逻辑，接收一个 `api` 对象作为参数，用于注册钩子。
 
 ## API 概览
 
 Runtime 插件 API 主要分为以下几类：
 
--   **信息获取**：获取运行时配置和钩子函数。
--   **生命周期钩子**：在应用渲染的不同阶段执行自定义逻辑。
+- **信息获取**：获取运行时配置和钩子函数。
+- **生命周期钩子**：在应用渲染的不同阶段执行自定义逻辑。
 
 ### 信息获取
 
@@ -53,7 +52,7 @@ Runtime 插件 API 主要分为以下几类：
 
 获取用户在 `modern.runtime.ts` 文件中定义的运行时配置。
 
--   **用法**:
+- **用法**:
 
 ```ts
 const config = api.getRuntimeConfig();
@@ -69,16 +68,18 @@ console.log(config.myCustomSetting);
 
 获取可用于手动触发的钩子函数。
 
--   **类型：**
+- **类型：**
 
 ```ts
 () => {
-  onBeforeRender: { call: (context: any) => Promise<void> };
+  onBeforeRender: {
+    call: (context: any) => Promise<void>;
+  }
   // 其他钩子...
 };
 ```
 
--   **用法：**
+- **用法：**
 
 ```ts
 const hooks = api.getHooks();
@@ -91,21 +92,24 @@ await hooks.onBeforeRender.call(myContext);
 
 在应用渲染（包括服务器端渲染和客户端渲染）之前执行。您可以在此钩子中执行数据预取、修改渲染上下文等操作。
 
--   **类型：**
+- **类型：**
 
-    ```ts
-    type OnBeforeRenderFn<RuntimeContext> = (context: RuntimeContext) => Promise<void> | void;
-    ```
-    `RuntimeContext` 包含当前请求的上下文信息，如请求对象、响应对象等。
+  ```ts
+  type OnBeforeRenderFn<RuntimeContext> = (
+    context: RuntimeContext,
+  ) => Promise<void> | void;
+  ```
 
--   **用法：**
+  `RuntimeContext` 包含当前请求的上下文信息，如请求对象、响应对象等。
 
-    ```ts
-    api.onBeforeRender(async (context) => {
-      const data = await fetchData(context.req);
-      context.data = data; // 将数据添加到上下文中
-    });
-    ```
+- **用法：**
+
+  ```ts
+  api.onBeforeRender(async context => {
+    const data = await fetchData(context.req);
+    context.data = data; // 将数据添加到上下文中
+  });
+  ```
 
 :::warning
 
@@ -118,35 +122,33 @@ await hooks.onBeforeRender.call(myContext);
 
 允许您使用自定义的 React 组件包裹应用的根组件。常用于添加全局的 Provider、布局组件等。
 
--   **类型：**
-
-    ```ts
-    type WrapRootFn = (
-      App: React.ComponentType<any>
-    ) => React.ComponentType<any>;
-    ```
-
--   **用法：**
-
-    ```ts
-    api.wrapRoot((App) => {
-      const AppWrapper = (props) => {
-        return (
-          <MyGlobalProvider>
-            <Layout>
-              <App {...props} /> {/* 确保传递 props */}
-            </Layout>
-          </MyGlobalProvider>
-        );
-      };
-      return AppWrapper;
-    });
-    ```
+- **类型：**
+
+  ```ts
+  type WrapRootFn = (App: React.ComponentType<any>) => React.ComponentType<any>;
+  ```
+
+- **用法：**
+
+  ```ts
+  api.wrapRoot(App => {
+    const AppWrapper = props => {
+      return (
+        <MyGlobalProvider>
+          <Layout>
+            <App {...props} /> {/* 确保传递 props */}
+          </Layout>
+        </MyGlobalProvider>
+      );
+    };
+    return AppWrapper;
+  });
+  ```
 
 :::warning
 
--   **务必将 `props` 传递给原始的 `App` 组件**，否则可能导致应用无法正常工作。
--  `wrapRoot` 返回的组件会在每次渲染时重新创建，因此应避免在其中定义复杂的逻辑或状态。
+- **务必将 `props` 传递给原始的 `App` 组件**，否则可能导致应用无法正常工作。
+- `wrapRoot` 返回的组件会在每次渲染时重新创建，因此应避免在其中定义复杂的逻辑或状态。
 
 :::
 
@@ -157,12 +159,12 @@ await hooks.onBeforeRender.call(myContext);
 您可以组合使用多个钩子来实现更复杂的功能。例如，您可以使用 `onBeforeRender` 获取数据，然后使用 `wrapRoot` 将数据通过 Context 传递给整个应用：
 
 ```ts
-import { RuntimePluginFuture, RuntimeReactContext } from '@modern-js/runtime';
+import { RuntimePlugin, RuntimeContext } from '@modern-js/runtime';
 import { useContext, createContext } from 'react';
 
 export const ThemeContext = createContext<{ theme: string } | null>(null);
 
-export const themePlugin = (): RuntimePluginFuture => {
+export const themePlugin = (): RuntimePlugin => {
   return {
     name: 'theme-plugin',
     setup: api => {
@@ -177,7 +179,7 @@ export const themePlugin = (): RuntimePluginFuture => {
 
       api.wrapRoot(App => {
         return props => {
-          const context = useContext(RuntimeReactContext);
+          const context = useContext(RuntimeContext);
           return (
             <ThemeContext.Provider value={context.data}>
               <App {...props} />

package/docs/zh/plugin/runtime-plugins/migration.mdx

@@ -6,7 +6,7 @@ Modern.js 插件系统持续演进，为了提供更清晰的 API 和更强大
 
 ### 迁移步骤总览
 
-1.  **更新插件类型定义**：将 `Plugin` 类型替换为 `RuntimePluginFuture`。
+1.  **更新插件类型定义**：将 `Plugin` 类型替换为 `RuntimePlugin`。
 2.  **调整 Hooks 调用方式**：从 `return hooks` 模式迁移到 `api.xxx` 直接调用。
 3.  **替换已变更的 API**：参照详细的 API 映射表，更新您的代码。
 
@@ -23,12 +23,12 @@ import type { Plugin } from '@modern-js/runtime';
 const plugin: Plugin = { ... };
 
 // 新版写法
-import type { RuntimePluginFuture } from '@modern-js/runtime';
+import type { RuntimePlugin } from '@modern-js/runtime';
 
-const plugin: RuntimePluginFuture = { ... };
+const plugin: RuntimePlugin = { ... };
 ```
 
-**说明：** `RuntimePluginFuture` 类型是新版插件的标准定义，它带来了更好的类型推断和更清晰的 API 结构。
+**说明：** `RuntimePlugin` 类型是新版插件的标准定义，它带来了更好的类型推断和更清晰的 API 结构。
 
 #### 调整 Hooks 调用方式
 
@@ -38,15 +38,19 @@ const plugin: RuntimePluginFuture = { ... };
 // 旧版写法 (return hooks)
 {
   setup: () => ({
-    beforeRender({ req, res }) { /*...*/ }
-  })
+    beforeRender({ req, res }) {
+      /*...*/
+    },
+  });
 }
 
 // 新版写法 (api.xxx)
 {
   setup: api => {
-    api.onBeforeRender(({ req, res }) => { /*...*/ })
-  }
+    api.onBeforeRender(({ req, res }) => {
+      /*...*/
+    });
+  };
 }
 ```
 
@@ -56,13 +60,14 @@ const plugin: RuntimePluginFuture = { ... };
 
 为了保持 API 的一致性和清晰性，我们对部分 API 的名称进行了调整。同时，`hoc` 和 `init` 这两个 Hook 已被移除，请使用新的 Hook 进行替代。下表列出了所有变更的 API 及其新旧对应关系：
 
-| 旧版 API      | 新版 API          | 说明                                                                                                                     |
-| :------------ | :---------------- | :----------------------------------------------------------------------------------------------------------------------- |
-| `beforeRender` | `onBeforeRender`  | 在应用渲染前执行。                                                                                                       |
-| `hoc`         | `wrapRoot`        | **重要变更：** 用于包裹根组件，实现高阶组件 (HOC) 的功能。请确保将 props 传递给原始组件。                               |
-| `init`        | `onBeforeRender`  | **重要变更：** 在应用渲染前执行初始化逻辑。                                                                                 |
+| 旧版 API       | 新版 API         | 说明                                                                                      |
+| :------------- | :--------------- | :---------------------------------------------------------------------------------------- |
+| `beforeRender` | `onBeforeRender` | 在应用渲染前执行。                                                                        |
+| `hoc`          | `wrapRoot`       | **重要变更：** 用于包裹根组件，实现高阶组件 (HOC) 的功能。请确保将 props 传递给原始组件。 |
+| `init`         | `onBeforeRender` | **重要变更：** 在应用渲染前执行初始化逻辑。                                               |
 
 **说明：**
+
 - `onBeforeRender` 替代了原来的 `beforeRender` 和 `init`，分别用于渲染前逻辑和初始化。
 - `wrapRoot` 替代了 `hoc`，用于实现高阶组件功能，使用时务必注意 props 的传递。
 
@@ -71,14 +76,18 @@ const plugin: RuntimePluginFuture = { ... };
 ```typescript
 {
   setup: api => {
-    api.wrapRoot((App) => {
-      const AppWrapper = (props) => {
+    api.wrapRoot(App => {
+      const AppWrapper = props => {
         // 确保将 props 传递给原始组件
-        return <Provider value={xx}><App {...props}/></Provider>;
+        return (
+          <Provider value={xx}>
+            <App {...props} />
+          </Provider>
+        );
       };
       return AppWrapper;
     });
-  }
+  };
 }
 ```
 

package/docs/zh/tutorials/_meta.json

@@ -1,14 +1,4 @@
 [
-  {
-    "type": "dir",
-    "name": "foundations",
-    "label": "foundations"
-  },
-  {
-    "type": "dir",
-    "name": "first-app",
-    "label": "first-app"
-  },
   {
     "type": "dir",
     "name": "examples",

package/docs/zh/tutorials/examples/csr-auth.mdx

@@ -4,7 +4,7 @@ title: 路由鉴权
 
 # 路由鉴权
 
-Modern.js 默认提供的路由方式是基于 React Router 6 的约定式路由，具体可查看[路由方案](/guides/basic-features/routes.html#路由方案)。
+Modern.js 默认提供的路由方式是基于 React Router v7 的约定式路由，具体可查看[路由方案](/guides/basic-features/routes/routes#路由方案)。
 
 在一个 Web 应用中如果存在多个路由，我们可能需要对部分路由进行鉴权后才能访问。例如下面这个案例：
 

package/docs/zh/tutorials/foundations/introduction.mdx

@@ -3,37 +3,20 @@ title: 介绍
 sidebar_position: 1
 ---
 
-# 介绍
+# Modern.js 示例库
 
-欢迎来到 Modern.js 教程！
+欢迎来到 Modern.js 示例库！这里提供实用的代码示例，帮助你快速上手 Modern.js。
 
-阅读本栏目后，你将初步理解 Modern.js，并使用 Modern.js 创建第一个应用。
+如果你是第一次接触 Modern.js，建议先阅读 [Modern.js 介绍](/guides/get-started/introduction)。
 
-## Modern.js 是什么
-
-如果你对 Modern.js 还不了解，可以先阅读 [Modern.js 介绍](/guides/get-started/introduction)。
-
-## 实战教程
-
-我们准备了一个创建「联系人列表应用」的实战教程，你可以按照教程一步步创建一个应用，并了解到 Modern.js 中的以下实践：
-
-- 创建项目
-- 使用 antd 组件库
-- 集成 Tailwind CSS
-- 客户端路由
-- 数据获取
-- 状态管理
-- 容器组件
-- 新建入口
-- ...
-
-## 案例
-
-我们提供了一些在开发过程中常用的案例供你参考，可以在这里找到 Modern.js 提供的一些功能组合的使用方式，我们将持续完善这里的案例。
+## 📚 示例列表
 
 import ExampleList from '@site-docs/components/turtorials-example-list';
 
 <ExampleList />
 
-下面就让我们从 [创建项目](tutorials/first-app/c01-start) 开始吧！
+---
+
+## 💡 贡献示例
 
+如果你有好的示例想要分享，欢迎通过 [GitHub](https://github.com/web-infra-dev/modern.js) 提交 PR！

package/i18n.json

@@ -111,26 +111,10 @@
     "zh": "Rsbuild 插件",
     "en": "Rsbuild Plugins"
   },
-  "reduck": {
-    "zh": "Reduck 状态管理",
-    "en": "Reduck State Manager"
-  },
   "module-federation": {
     "zh": "模块联邦",
     "en": "Module Federation"
   },
-  "generator": {
-    "zh": "项目生成器",
-    "en": "Project Generator"
-  },
-  "new-command": {
-    "zh": "New 命令",
-    "en": "New Command"
-  },
-  "generator-plugin": {
-    "zh": "生成器插件",
-    "en": "Generator Plugin"
-  },
   "examples": {
     "zh": "示例",
     "en": "Examples"

package/package.json

@@ -6,7 +6,7 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/web-infra-dev/modern.js",
-    "directory": "packages/document/main-doc"
+    "directory": "packages/document"
   },
   "license": "MIT",
   "keywords": [
@@ -15,29 +15,29 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.69.5",
+  "version": "3.0.0-alpha.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "dependencies": {
-    "mermaid": "^11.4.1",
-    "@modern-js/sandpack-react": "2.69.5"
+    "mermaid": "^11.12.2",
+    "@modern-js/sandpack-react": "3.0.0-alpha.0"
   },
   "devDependencies": {
     "@rsbuild/plugin-sass": "1.4.0",
-    "@shikijs/transformers": "^3.4.2",
-    "@rspress/shared": "2.0.0-beta.16",
-    "@rspress/plugin-llms": "2.0.0-beta.16",
+    "@shikijs/transformers": "^3.20.0",
+    "@rspress/shared": "2.0.0-rc.0",
+    "@rspress/plugin-llms": "2.0.0-rc.0",
     "@types/fs-extra": "9.0.13",
-    "@types/node": "^16",
+    "@types/node": "^20",
     "classnames": "^2.5.1",
     "clsx": "^1.2.1",
     "fs-extra": "^10.1.0",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
-    "rspress": "2.0.0-beta.16",
-    "ts-node": "^10.9.1",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "@rspress/core": "2.0.0-rc.0",
+    "ts-node": "^10.9.2",
     "typescript": "^5"
   },
   "scripts": {

package/rspress.config.ts

@@ -1,8 +1,8 @@
 import path from 'path';
 import { pluginSass } from '@rsbuild/plugin-sass';
+import { defineConfig } from '@rspress/core';
 import { pluginLlms } from '@rspress/plugin-llms';
 import { transformerNotationHighlight } from '@shikijs/transformers';
-import { defineConfig } from 'rspress/config';
 
 const docPath = path.join(__dirname, 'docs');
 
@@ -63,7 +63,7 @@ export default defineConfig({
     ],
     editLink: {
       docRepoBaseUrl:
-        'https://github.com/web-infra-dev/modern.js/tree/main/packages/document/main-doc/docs',
+        'https://github.com/web-infra-dev/modern.js/tree/main/packages/document/docs',
       text: 'Edit this page on GitHub',
     },
     socialLinks: [
@@ -77,12 +77,6 @@ export default defineConfig({
         mode: 'link',
         content: 'https://github.com/web-infra-dev/modern.js',
       },
-      {
-        icon: 'lark',
-        mode: 'link',
-        content:
-          'https://applink.larkoffice.com/client/chat/chatter/add_by_link?link_token=d21hc667-9403-48a9-ba32-bc1440a80279',
-      },
     ],
   },
   route: {
@@ -98,6 +92,9 @@ export default defineConfig({
     },
   ],
   builderConfig: {
+    performance: {
+      buildCache: false,
+    },
     tools: {
       // FIXME: use `?raw` after upgrading to Rsbuild@1.4.0, https://github.com/web-infra-dev/rsbuild/pull/5355
       rspack(_config, { addRules }) {