@modern-js/main-doc 2.66.0 → 2.66.1-alpha.0

package/docs/zh/guides/basic-features/render/before-render.mdx

@@ -0,0 +1,115 @@
+# 渲染预处理 (Render Preprocessing)
+
+在某些场景下，应用需要在渲染前执行预处理操作。Modern.js 推荐使用 **[Runtime 插件 (Runtime Plugin)](/plugin/introduction.html#runtime-插件)** 来实现这类逻辑。
+
+## 定义 Runtime 插件
+
+```ts
+import type { RuntimePluginFuture } from '@modern-js/runtime';
+
+const myRuntimePlugin = (): RuntimePluginFuture => ({
+  name: 'my-runtime-plugin',
+  setup: (api) => {
+    api.onBeforeRender((context) => {
+      // 在渲染前执行的逻辑
+      console.log('Before rendering:', context);
+    });
+  },
+});
+
+export default myRuntimePlugin;
+```
+
+## 注册插件
+
+在项目 `src/modern.runtime.ts` 文件中注册插件：
+
+```ts
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import myRuntimePlugin from './plugins/myRuntimePlugin';
+
+export default defineRuntimeConfig({
+  plugins: [myRuntimePlugin()],
+});
+```
+
+## 应用场景 -- 全局数据注入
+
+通过 `onBeforeRender` 钩子的 `context` 参数，可以向应用注入全局数据。应用的组件可以通过 `useRuntimeContext` Hook 访问这些数据。
+
+:::info
+
+此功能在以下场景中特别有用：
+* 需要页面级前置数据的应用
+* 自定义数据注入流程
+* 框架迁移场景（例如从 Next.js 迁移）
+
+:::
+
+**定义数据注入插件**
+
+```ts
+import type { RuntimePluginFuture } from '@modern-js/runtime';
+
+const dataInjectionPlugin = (): RuntimePluginFuture => ({
+  name: 'data-injection-plugin',
+  setup: api => {
+    api.onBeforeRender(context => {
+      // 向 context 中注入数据
+      context.message = 'Hello World';
+    });
+  },
+});
+
+export default dataInjectionPlugin;
+```
+
+**在组件中使用注入的数据**
+
+```tsx
+import { useRuntimeContext } from '@modern-js/runtime';
+
+export default function MyComponent() {
+  const context = useRuntimeContext();
+  const { message } = context;
+
+  return <div>{message}</div>;
+}
+```
+
+**结合 SSR 使用**
+
+在 SSR 场景下，浏览器端可以获取服务端渲染期间通过 `onBeforeRender` 注入的数据。开发者可以根据需求决定是否在浏览器端重新获取数据来覆盖服务端数据。
+
+```ts
+import type { RuntimePluginFuture } from '@modern-js/runtime';
+
+const dataInjectionPlugin = (): RuntimePluginFuture => ({
+  name: 'data-injection-plugin',
+  setup: api => {
+    api.onBeforeRender(context => {
+      if (process.env.MODERN_TARGET === 'node') {
+        // 服务端渲染时设置数据
+        context.message = 'Hello World By Server';
+      } else {
+        // 客户端渲染时检查数据
+        if (!context.message) {
+          // 如果没有获取到服务端数据，则设置客户端数据
+          context.message = 'Hello World By Client';
+        }
+      }
+    });
+  },
+});
+
+export default dataInjectionPlugin;
+```
+
+## 兼容性说明
+
+在 Modern.js 的早期版本中，支持通过 `routes/layout.tsx` 中的 `init` 钩子以及 `App.init` 方法来添加渲染预处理逻辑。这些方式目前仍然**被支持**，但我们**强烈推荐**使用 Runtime 插件实现。
+
+:::warning
+
+未来版本中，`routes/layout.tsx` 的 `init` 钩子和 `App.init` 方法将逐步**废弃**。建议尽早迁移到 Runtime 插件方案。
+:::

package/docs/zh/guides/basic-features/routes.mdx

@@ -483,101 +483,6 @@ Modern.js 支持通过 `loading.tsx` 文件来解决这个问题，`routes/` 下
 :::
 
 
-## 运行时配置
-
-{/* Todo 移到动运行时配置章节 */}
-
-在根 `<Layout>` 组件中（`routes/layout.ts`），可以动态地定义运行时配置：
-
-```tsx title="src/routes/layout.tsx"
-// 定义运行时配置
-import type { AppConfig } from '@modern-js/runtime';
-
-export const config = (): AppConfig => {
-  return {
-    router: {
-      createRoutes() {
-        return [
-          {
-            path: 'modern',
-            element: <div>modern</div>,
-          },
-        ];
-      },
-    },
-  };
-};
-```
-
-## 渲染前的钩子
-
-{/* Todo 移到动运行时配置章节 */}
-
-在有些场景下，需要在应用渲染前做一些操作，可以在 `routes/layout.tsx` 中定义 `init` 钩子，`init` 在客户端和服务端均会执行，基本使用示例如下：
-
-```ts title="src/routes/layout.tsx"
-import type { RuntimeContext } from '@modern-js/runtime';
-
-export const init = (context: RuntimeContext) => {
-  // do something
-};
-```
-
-通过 `init` 钩子可以挂载一些全局的数据，在应用的其他地方可以访问 `runtimeContext` 变量：
-
-:::note
-该功能在应用需要页面前置的数据、自定义数据注入或是框架迁移（如 Next.js）时会非常有用。
-
-:::
-
-```ts title="src/routes/layout.tsx"
-import { RuntimeContext } from '@modern-js/runtime';
-
-type InitialData = {
-  message: string;
-}
-
-export const init = (context: RuntimeContext): InitialData => {
-  return {
-    message: 'Hello World',
-  };
-};
-```
-
-```tsx title="src/routes/page.tsx"
-import { useRuntimeContext } from '@modern-js/runtime';
-
-export default () => {
-  const context = useRuntimeContext();
-  const { message } = context.initialData as InitialData;
-
-  return <div>{message}</div>;
-};
-```
-
-配合 SSR 功能时，浏览器端可以获取到 SSR 时 `init` 返回的数据，开发者可以自行判断是否要在浏览器端重新获取数据来覆盖 SSR 数据，例如：
-
-```tsx title="src/routes/layout.tsx"
-import type { RuntimeContext } from '@modern-js/runtime';
-
-export const init = (runtimeContext: RuntimeContext) => {
-  if (process.env.MODERN_TARGET === 'node') {
-    return {
-      message: 'Hello World By Server',
-    };
-  } else {
-    const { context } = runtimeContext;
-    const data = context.getInitData();
-    // 如果没有获取到期望的数据
-    if (!data.message) {
-      return {
-        message: 'Hello World By Client',
-      };
-    }
-  }
-};
-```
-
 import Motivation from '@site-docs/components/convention-routing-motivation';
 
 <Motivation />

package/docs/zh/guides/topic-detail/micro-frontend/c02-development.mdx

@@ -14,9 +14,9 @@ title: 体验微前端
 
 目前项目的路由模式分为以下三种
 
-- 约定式路由 (设置 `router: true` 并使用文件路由)
-- 自控式路由 (设置 `router: true` 并自己创建 `BrowserRouter` 等)
-- 其他 (设置 `router: false` 项目内自己安装和使用 `react-router-dom`)
+- [约定式路由](/guides/concept/entries.html#约定式路由)
+- [自控式路由](/guides/concept/entries.html#自控式路由)
+- 其他 (项目自行安装和使用 `react-router-dom`)
 
 在本教程中我们会为主应用创建两个子应用 Table 和 Dashboard (Table 为约定式路由，Dashboard 为自控式路由)
 
@@ -206,7 +206,6 @@ export default defineConfig({
   },
   runtime: {
     router: true,
-    state: true,
   },
   deploy: {
     microFrontend: true,
@@ -259,7 +258,6 @@ export default defineConfig({
   },
   runtime: {
     router: true,
-    state: true,
   },
   deploy: {
     microFrontend: true,

package/docs/zh/guides/topic-detail/micro-frontend/c03-main-app.mdx

@@ -35,8 +35,10 @@ import MicroRuntimeConfig from '@site-docs/components/micro-runtime-config';
 
 通过该函数可以拉取远程的子应用列表，并将其注册至运行时框架：
 
-```ts title="App.tsx"
-defineConfig(App, {
+```ts title="src/modern.runtime.ts"
+import { defineRuntimeConfig } from '@modern-js/runtime';
+
+export default defineRuntimeConfig({
   masterApp: {
     manifest: {
       getAppList: async () => {

package/docs/zh/guides/topic-detail/model/auto-actions.mdx

@@ -1,7 +1,3 @@
----
-sidebar_position: 6
-title: 自动生成 Actions
----
 # 自动生成 Actions
 
 在 [快速上手](/guides/topic-detail/model/quick-start) 中，我们实现最简单的计数器 Model 也需要 10 行代码。

package/docs/zh/guides/topic-detail/model/computed-state.mdx

@@ -1,7 +1,3 @@
----
-sidebar_position: 4
-title: 衍生状态
----
 # 衍生状态
 
 一些场景中，组件需要对 Model 中的 State 进行进一步计算，才能在组件中使用，这部分逻辑可以直接写在组件内部，也可以通过 Model 的衍生状态实现。

package/docs/zh/guides/topic-detail/model/define-model.mdx

@@ -1,7 +1,3 @@
----
-sidebar_position: 2
-title: 创建 Model
----
 # 创建 Model
 
 上一节的计数器应用中，我们简单演示了如何创建一个 Model。本节我们将详细介绍 Model 的创建方法。
@@ -24,6 +20,7 @@ const fooModel = model('foo').define({
 ```
 
 :::info
+
 - Model 中的 Action 中不能包含有副作用的逻辑，如请求 HTTP 接口，访问 localStorage 等。
 - `setValue` 内部直接修改了入参 State，看起来是违反了纯函数的定义，实际上 Reduck 内部使用 [immer](https://github.com/immerjs/immer) 来修改不可变对象，保证了这种写法不会影响对象的不可变性，所以 `setValue` 仍然是一个纯函数。当然，你也可以直接在 Action 中返回一个新对象，不过这样的写法会更加复杂一些。
 

package/docs/zh/guides/topic-detail/model/faq.mdx

@@ -1,8 +1,3 @@
----
-sidebar_position: 13
-title: 常见问题
----
-
 # 常见问题
 
 ## 浏览器兼容性

package/docs/zh/guides/topic-detail/model/manage-effects.mdx

@@ -1,7 +1,3 @@
----
-sidebar_position: 5
-title: 副作用管理
----
 # 副作用管理
 
 Model 中的 Action 必须是一个纯函数，执行过程中不会产生任何副作用。但在真实的业务中，我们会遇到很多副作用场景，如：请求 HTTP 接口获取状态数据，或者在更新状态的同时修改 localStorage、发送事件等。在 Reduck 中，是通过 Model 的 Effects 函数管理副作用的。

package/docs/zh/guides/topic-detail/model/model-communicate.mdx

@@ -1,7 +1,3 @@
----
-sidebar_position: 7
-title: Model 通信
----
 # Model 通信
 
 Model 通信，既指不同 Model 间的通信，也指同一个 Model 内部 Effects、Actions 之间的通信。
@@ -100,6 +96,7 @@ Modern.js 默认开启 [自动生成 actions](./auto-actions.mdx)，所以 `step
 ![communicate-models](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/models-communicate.gif)
 
 :::info 补充信息
+
 - 本节完整的[示例代码](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/runtime-api/models-communication)。
 - 相关 API 的更多介绍，请参考：[model](/apis/app/runtime/model/model_#函数类型)。
 

package/docs/zh/guides/topic-detail/model/performance.mdx

@@ -1,7 +1,3 @@
----
-sidebar_position: 8
-title: 性能优化
----
 # 性能优化
 
 Reduck 内部已经做了大量性能优化工作，一般情况下不需要考虑性能问题。不过当对性能比较敏感、或者遇到了性能问题，可以考虑从以下 3 个方面，进行更有针对性的性能优化。

package/docs/zh/guides/topic-detail/model/quick-start.mdx

@@ -1,15 +1,14 @@
----
-sidebar_position: 1
-title: 快速上手
----
+# 快速上手
 
 :::caution
 新项目不再推荐使用 Reduck，可以使用社区中的状态管理工具，例如 [Jotai](https://jotai.org/)、[zustand](https://zustand.docs.pmnd.rs/getting-started/introduction)、[valtio](https://valtio.dev/docs/introduction/getting-started) 等。
 :::
 
-# 快速上手
+import ReduckNotify from '@site-docs/components/reduck-notify';
 
-import ReduckMigration from "@site-docs/components/reduck-migration"
+<ReduckNotify />
+
+import ReduckMigration from '@site-docs/components/reduck-migration';
 
 <ReduckMigration />
 
@@ -22,8 +21,8 @@ Reduck 在 MVC 模式中，扮演 M(Model) 的角色，React UI Component 对应
 Modern.js 的状态管理解决方案，是通过内置 Reduck 实现的。在 Modern.js 中使用 Reduck，不仅免去了手动集成的环节，而且所有 Reduck API 都可以从 Modern.js 的 Runtime 包中直接导入使用，具有更好的一致性体验。
 
 :::info
-1. Modern.js 中使用 Reduck API，需要先设置 [runtime.state](/configure/app/runtime/state) 以启用状态管理插件。
-2. Reduck 也可以脱离 Modern.js 作为状态管理库[单独使用](/guides/topic-detail/model/use-out-of-modernjs)。
+
+Reduck 也可以脱离 Modern.js 作为状态管理库[单独使用](/guides/topic-detail/model/use-out-of-modernjs)。
 
 :::
 

package/docs/zh/guides/topic-detail/model/redux-integration.mdx

@@ -1,7 +1,3 @@
----
-sidebar_position: 11
-title: Redux 生态集成
----
 # Redux 生态集成
 
 Reduck 基于 Redux 实现，因此可以使用 Redux [生态的库](https://redux.js.org/introduction/ecosystem)，实现功能增强。通过 [`Provider`](/apis/app/runtime/model/Provider) 、[`createApp`](/apis/app/runtime/model/create-app) 和 [`createStore`](/apis/app/runtime/model/create-store) 等 API ，可以设置使用 Redux 的 [中间件](https://redux.js.org/understanding/thinking-in-redux/glossary#middleware) 和 [Store Enhancer](https://redux.js.org/understanding/thinking-in-redux/glossary#store-enhancer)；使用 [`createStore`](/apis/app/runtime/model/create-store) 还可以完全掌控 Store 的创建过程。

package/docs/zh/guides/topic-detail/model/typescript-best-practice.mdx

@@ -1,7 +1,3 @@
----
-sidebar_position: 10
-title: TS 最佳实践
----
 # TS 最佳实践
 
 Reduck 对 TS 提供了良好的支持，大部分使用场景下，无需任何额外工作，就可以直接获得 API 的 TS 类型提示。本节，将对其他的一些使用场景，做补充介绍。

package/docs/zh/guides/topic-detail/model/use-model.mdx

@@ -1,8 +1,3 @@
----
-sidebar_position: 3
-title: 使用 Model
----
-
 # 使用 Model
 
 ## 在组件内使用

package/docs/zh/guides/topic-detail/model/use-out-of-modernjs.mdx

@@ -1,7 +1,3 @@
----
-sidebar_position: 12
-title: 单独使用 Reduck
----
 # 单独使用 Reduck
 
 在 Modern.js 以外，单独集成 Reduck 使用时，主要需要做以下修改：

package/package.json

@@ -15,7 +15,7 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.66.0",
+  "version": "2.66.1-alpha.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"