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

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

@@ -1,13 +1,12 @@
----
-sidebar_position: 1
-title: Quick Start
----
+# Quick Start
 
 :::caution
 New projects are no longer recommended to use Reduck. You can use state management tools from the community, such as [Jotai](https://jotai.org/), [zustand](https://zustand.docs.pmnd.rs/getting-started/introduction), [valtio](https://valtio.dev/docs/introduction/getting-started), etc.
 :::
 
-# Quick Start
+import ReduckNotify from '@site-docs-en/components/reduck-notify';
+
+<ReduckNotify />
 
 import ReduckMigration from "@site-docs-en/components/reduck-migration"
 
@@ -22,8 +21,7 @@ In the MVC pattern, Reduck plays the role of M(Model), React UI Component corres
 The state management solution of Modern.js is implemented through built-in Reduck. Using Reduck in Modern.js not only eliminates the manual integration process, but also allows all Reduck APIs to be imported and used directly from the Modern.js Runtime package, providing a better consistency experience.
 
 :::info
-1. To use Reduck APIs in Modern.js, you need to set [runtime.state](/configure/app/runtime/state) to enable the state management plugin.
-2. Reduck can also be used separately as a state management library [outside of Modern.js](/guides/topic-detail/model/use-out-of-modernjs).
+Reduck can also be used separately as a state management library [outside of Modern.js](/guides/topic-detail/model/use-out-of-modernjs).
 
 :::
 

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

@@ -1,7 +1,3 @@
----
-sidebar_position: 11
-title: Ecosystem Integration
----
 # Redux Ecosystem Integration
 
 Reduck is based on Redux, so you can use libraries from the [Redux ecosystem](https://redux.js.org/introduction/ecosystem) to enhance its functionality. APIs like [`Provider`](/apis/app/runtime/model/Provider), [`createApp`](/apis/app/runtime/model/create-app), and [`createStore`](/apis/app/runtime/model/create-store) allow you to configure the use of [middlewares](https://redux.js.org/understanding/thinking-in-redux/glossary#middleware) and [store enhancers](https://redux.js.org/understanding/thinking-in-redux/glossary#store-enhancer); and using [`createStore`](/apis/app/runtime/model/create-store), you can take complete control over the process of creating the store.

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

@@ -1,7 +1,3 @@
----
-sidebar_position: 10
-title: TS Best Practices
----
 # TS Best Practices
 
 Reduck provides excellent support for TypeScript, and in most cases, you can get API type prompts directly without any extra work. In this section, we will provide additional information on other usage scenarios.

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

@@ -1,8 +1,3 @@
----
-sidebar_position: 3
-title: Use Models
----
-
 # Use Models
 
 ## Using Models in Components

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

@@ -1,7 +1,3 @@
----
-sidebar_position: 12
-title: Using Reduck Separately
----
 # Using Reduck Separately
 
 When integrating Reduck separately from Modern.js, the following modifications need to be made:

package/docs/zh/apis/app/hooks/src/app.mdx

@@ -2,6 +2,7 @@
 title: App.[tj]sx
 sidebar_position: 1
 ---
+
 # App.[tj]sx
 
 应用使用[自控路由](/guides/concept/entries.html#自控式路由)时的入口标识符。
@@ -9,35 +10,26 @@ sidebar_position: 1
 `App.[tj]sx` 并不是实际的应用入口，Modern.js 会自动生成真正的构建打包的入口文件, 内容大致如下：
 
 ```js
-import React from 'react';
-import ReactDOM from 'react-dom/client';
-import { createApp, bootstrap } from '@modern-js/runtime';
-// App.[jt]sx
+// runtime-global-context
+import { setGlobalContext } from '@modern-js/runtime/context';
 import App from '@_modern_js_src/App';
-// runtime plugin
-import { router } from '@modern-js/runtime/plugins';
-
-const IS_BROWSER = typeof window !== 'undefined' && window.name !== 'nodejs';
-const MOUNT_ID = 'root';
-
-let AppWrapper = null;
-
-function render() {
-  AppWrapper = createApp({
-    plugins: [
-     router({...{"serverBase":["/"]}, ...App.config?.router}),
-    ]
-  })(App)
-  if (IS_BROWSER) {
-    bootstrap(AppWrapper, MOUNT_ID, null, ReactDOM);
-  }
-  return AppWrapper
-}
-
-AppWrapper = render();
-export default AppWrapper;
+
+setGlobalContext({
+  App,
+});
+
+// index.tsx
+import './runtime-global-context';
+import { createRoot } from '@modern-js/runtime/react';
+import { render } from '@modern-js/runtime/browser';
+
+const ModernRoot = createRoot();
+
+render(<ModernRoot />, 'root');
 ```
 
+`createRoot` 执行时，会去获取注册的 Globa App，生成真实的 React 组件。
+
 :::note
 在多入口的场景下，每个入口都可以拥有独立的 `App.[jt]sx`，详见[入口](/guides/concept/entries)。
 

package/docs/zh/apis/app/hooks/src/modern.runtime.mdx

@@ -0,0 +1,9 @@
+---
+title: modern.runtime.[tj]s
+sidebar_position: 4
+---
+# modern.runtime.[tj]s
+
+Modern.js Runtime 配置文件, 通过该文件可以对当前项目的 Runtime 能力进行个性化配置。
+
+了解配置的具体用法，请参考 [Runtime 配置](/configure/app/runtime/0-intro.html)。

package/docs/zh/apis/app/runtime/app/define-config.mdx

@@ -4,6 +4,11 @@ title: defineConfig
 ---
 # defineConfig
 
+:::warning
+
+该 API 即将废弃，推荐使用 `src/modern.runtime.ts` 定义 Runtime 配置，同时支持静态配置和动态配置，使用姿势插件[Runtime 配置](/configure/app/runtime/0-intro.html)
+:::
+
 用于动态配置应用。
 
 ## 使用姿势

package/docs/zh/components/enable-micro-frontend.mdx

@@ -1,23 +1,30 @@
-```js title="modern.config.ts"
+```ts title="modern.config.ts"
 import { appTools, defineConfig } from '@modern-js/app-tools';
 import { garfishPlugin } from '@modern-js/plugin-garfish';
 
 export default defineConfig({
   runtime: {
     router: true,
-    masterApp: {
-      apps: [{
-        name: 'Table',
-        entry: 'http://localhost:8081',
-        // activeWhen: '/table'
-      }, {
-        name: 'Dashboard',
-        entry: 'http://localhost:8082'
-        // activeWhen: '/dashboard'
-      }]
-    },
   },
   plugins: [appTools(), garfishPlugin()],
 });
 
 ```
+
+```ts title="src/modern.runtime.ts"
+import { defineRuntimeConfig } from '@modern-js/runtime';
+
+export default defineRuntimeConfig({
+  masterApp: {
+    apps: [{
+      name: 'Table',
+      entry: 'http://localhost:8081',
+      // activeWhen: '/table'
+    }, {
+      name: 'Dashboard',
+      entry: 'http://localhost:8082'
+      // activeWhen: '/dashboard'
+    }]
+  },
+});
+```

package/docs/zh/components/micro-runtime-config.mdx

@@ -1,7 +1,7 @@
-```js title="src/App.tsx"
-import { defineConfig } from '@modern-js/runtime';
+```ts title="src/modern.runtime.ts"
+import { defineRuntimeConfig } from '@modern-js/runtime';
 
-defineConfig(App, {
+export default defineRuntimeConfig({
   masterApp: {
     apps: [{
       name: 'Table',

package/docs/zh/components/reduck-notify.mdx

@@ -0,0 +1,27 @@
+:::warning
+从 `MAJOR_VERSION.67.0` 起，Modern.js 不再默认提供 Reduck 状态管理能力。如果需要使用 Reduck，您需要安装并注册 state 插件。
+
+**安装步骤**
+
+1. 安装 `@modern-js/plugin-state` 依赖：
+
+```bash
+pnpm add @modern-js/plugin-state
+```
+
+2. 注册 state 插件：
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+import { statePlugin } from '@modern-js/plugin-state';
+
+export default defineConfig({
+  ...,
+  plugins: [
+    ...,
+    statePlugin(),
+  ],
+});
+```
+
+:::

package/docs/zh/configure/app/runtime/0-intro.mdx

@@ -1,120 +1,101 @@
----
-title: 总览
-sidebar_position: 1
----
+# 介绍
 
-# 总览
+Modern.js 的运行时（Runtime）配置需集中在 `src/modern.runtime.ts` 文件中声明。
 
-此节将介绍 Runtime 插件的配置。
-
-## 配置方式
-
-### runtime
-
-- **类型：** `Object`
+:::info
+如果项目中还没有此文件，请执行以下命令创建：
 
-runtime 配置方式如下：
+```bash
+touch src/modern.runtime.ts
+```
 
-#### 基本用法
+:::
 
-在 `modern.config.ts` 中配置
+## 基本配置
 
-```ts title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
+```tsx
+import { defineRuntimeConfig } from '@modern-js/runtime';
 
-export default defineConfig({
-  runtime: {
-    state: true,
-    router: true,
+export default defineRuntimeConfig({
+  router: {
+    // 路由配置
+  },
+  state: {
+    // 状态管理配置
   },
+  // 其他运行时模块...
 });
 ```
 
-#### 运行时配置
-
-通过 [`defineConfig`](/apis/app/runtime/app/define-config) API 配置：
-
-:::info
-当 runtime 配置中存在函数时，只能使用该方式进行配置。
-
-:::
+## 多入口配置
 
-import { Tabs, Tab as TabItem } from "@theme";
+对于多入口应用，`defineRuntimeConfig` 函数可以根据入口名称返回特定的配置：
 
-<Tabs>
-  <TabItem value="layout" label="约定式路由" default>
+```tsx
+import { defineRuntimeConfig } from '@modern-js/runtime';
 
-```tsx title="src/routes/layout.tsx"
-import type { AppConfig } from '@modern-js/runtime';
-
-export const config = (): AppConfig => {
-  return {
-    router: {
-      supportHtml5History: false
-    }
+export default defineRuntimeConfig(entryName => {
+  if (entryName === 'main') {
+    return {
+      router: {
+        // "main" 入口的路由配置
+      },
+      state: {
+        // "main" 入口的状态管理配置
+      },
+    };
   }
-};
-```
-
-  </TabItem>
-
-  <TabItem value="app" label="自控路由">
 
-```ts title="src/App.tsx"
-import { defineConfig } from '@modern-js/runtime';
-
-const App = () => {
-  /** */
-};
-
-defineConfig(App, {
-  router: {
-    supportHtml5History: false,
-  },
+  // 其他入口的配置
+  return {
+    masterApp: {
+      // 微前端配置示例
+    },
+  };
 });
-
-export default App;
 ```
 
-  </TabItem>
-</Tabs>
-
-:::info
-使用运行时配置，可以解决 Runtime 插件配置需要在运行时才能获取到具体内容问题。
-
-Runtime 插件运行时配置和直接在 `modern.config.ts` 中的配置默认会进行合并，且运行时配置优先级更高。
-
+:::tip
+使用 `src/modern.runtime.ts` 配置方式不支持导出异步函数，这与 Modern.js 的渲染方式有关。如果需要添加异步逻辑，请使用 **[Runtime 插件 (Runtime Plugin)](/plugin/introduction.html#runtime-插件)**。
 :::
 
 :::warning
-defineConfig 中只能定义 Runtime 插件的具体配置内容，确认是否开启插件还需要通过 `modern.config.ts` 中的配置决定。
-
+使用 `src/modern.runtime.ts` 配置方式需要 Modern.js 版本 **MAJOR_VERSION.66.0** 或更高版本。
 :::
 
-### runtimeByEntries
+## 配置方式演进
 
-- **类型：** `Object`
-- **默认值：**无
+在 MAJOR_VERSION.66.0 之前，运行时配置分散在多个位置：
 
-#### 说明
+1. `modern.config.ts` 中的 `runtime` 和 `runtimeByEntries` 字段
+2. 各入口的 `App.config` 或 `layout` 文件导出的 `config` 函数
 
-按入口添加 runtime 配置，选项属性同 runtime 一致，指定值会和 runtime 属性内容做替换合并操作。
+为提升可维护性，Modern.js 引入了统一的 `src/modern.runtime.ts` 配置入口。
 
-```ts title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
+### 旧配置方式（兼容但不推荐）
 
-export default defineConfig({
+```ts
+// modern.config.ts
+export default {
   runtime: {
-    state: false,
+    /* ... */
   },
   runtimeByEntries: {
-    entry1: {
-      state: true, // { state: true }
-    },
-    entry2: {
-      // { state: false, router: true }
-      router: true,
-    },
+    /* ... */
   },
-});
+};
+
+// App.config
+App.config = {
+  /* ... */
+};
+
+// layout 文件
+export const config = () => {
+  /* 动态配置逻辑 */
+};
 ```
+
+### 迁移建议
+
+强烈建议将所有运行时配置迁移至 `src/modern.runtime.ts`。虽然旧配置方式目前仍兼容，但计划在未来版本中逐步废弃。统一配置入口可避免配置分散，显著提高项目可维护性。

package/docs/zh/configure/app/usage.mdx

@@ -1,12 +1,8 @@
----
-sidebar_position: 0
----
-
 # 配置使用
 
-Modern.js 中有两种配置，分别是编译时配置和服务端运行时配置。
+Modern.js 中有三种配置，分别是编译时配置、运行时配置和服务端运行时配置。
 
-编译时配置可以在两个位置进行配置：
+**编译时配置**可以在两个位置进行配置：
 
 - 根路径下的 `modern.config.(ts|js|mjs)` 文件
 - `package.json` 文件
@@ -15,9 +11,14 @@ Modern.js 中有两种配置，分别是编译时配置和服务端运行时配
 Modern.js 不支持同时在 `package.json` 中和 `modern.config.ts` 中配置同一个配置项，推荐在 `modern.config.ts` 中进行配置。如果 Modern.js 检测到重复配置导致的冲突，将会抛出警告。
 :::
 
-服务端运行时配置可以在根路径下的 `modern.server-runtime.config.(ts|js|mjs)` 中进行配置。
+**运行时配置**可以在 `src/modern.runtime.(ts|js|mjs)` 文件中配置。
+
+{/* TODO server 配置文件更新 */}
+**服务端运行时配置**可以在根路径下的 `modern.server-runtime.config.(ts|js|mjs)` 中进行配置。
 
-## 在配置文件中配置
+## 编译时配置
+
+### 在配置文件中配置
 
 Modern.js 的配置文件定义在项目的根目录下，支持 `.ts`, `.js` 和 `.mjs` 格式：
 
@@ -25,7 +26,7 @@ Modern.js 的配置文件定义在项目的根目录下，支持 `.ts`, `.js`
 - `modern.config.js`
 - `modern.config.mjs`
 
-### modern.config.ts（推荐）
+#### modern.config.ts（推荐）
 
 我们推荐使用 `.ts` 格式的配置文件，它提供了友好的 TypeScript 类型提示，从而帮助你避免配置中的错误。
 
@@ -52,7 +53,7 @@ export default defineConfig({
 });
 ```
 
-### modern.config.js
+#### modern.config.js
 
 如果你在开发一个非 TypeScript 项目，可以使用 `.js` 格式的配置文件：
 
@@ -76,7 +77,7 @@ export default {
 };
 ```
 
-### 导出配置函数
+#### 导出配置函数
 
 Modern.js 支持在配置文件中导出一个函数，你可以在函数中动态计算配置，并返回给 Modern.js。
 
@@ -99,7 +100,7 @@ export default defineConfig(({ env, command }) => ({
   - 当运行 `modern build` 或 `modern serve` 时，`env` 的值为 `production`。
 - `command`：对应当前运行的命令，如 `dev`、`start`、`build`、`serve`。
 
-### 导出异步函数
+#### 导出异步函数
 
 Modern.js 也支持在配置文件中导出一个异步函数，你可以在函数中进行一些异步操作：
 
@@ -117,7 +118,7 @@ export default defineConfig(async ({ env, command }) => {
 });
 ```
 
-### 指定配置文件
+#### 指定配置文件
 
 Modern.js 命令行支持通过 `--config` 选项来指定配置文件的名称。
 
@@ -138,7 +139,7 @@ Modern.js 命令行支持通过 `--config` 选项来指定配置文件的名称
 $ modern build -c modern.prod.config.js
 ```
 
-## 在 package.json 中配置（不推荐）
+### 在 package.json 中配置（不推荐）
 
 除了配置文件外，你也可以在 `package.json` 中的 `modernConfig` 字段下设置配置项，如：
 
@@ -156,16 +157,16 @@ $ modern build -c modern.prod.config.js
 
 由于 JSON 文件格式的限制，`package.json` 中只能定义数字、字符串、布尔值、数组等简单类型的值，当我们需要设置函数类型的值时，建议在 Modern.js 配置文件中进行设置。
 
-### 注意事项
+#### 注意事项
 
 - 不建议同时使用 `package.json` 和 `modern.config.js` 进行配置。如果同时使用了两者并出现配置冲突，Modern.js 会在命令行进行提示错误。
 - `@modern-js/runtime` 导出了同名的 [defineConfig](/apis/app/runtime/app/define-config) API，请注意区分。
 
-## 本地调试配置
+### 本地调试配置
 
 为了便于本地调试配置，Modern.js 支持在项目根目录下创建 `modern.config.local.(ts|js|mjs)` 文件，用于覆盖 `modern.config.(ts|js|mjs)` 中的配置选项。
 
-### 示例
+#### 示例
 
 比如，项目的 `modern.config.ts` 中配置了端口号为 `3000`:
 
@@ -193,7 +194,7 @@ export default defineConfig({
 
 `modern.config.local.ts` 文件中的配置会与 `modern.config.ts` 中的配置进行深层合并，并覆盖 `modern.config.ts` 中的配置选项，因此 `server.port` 会被覆盖为 `3001`。
 
-### 注意事项
+#### 注意事项
 
 在使用 `modern.config.local.ts` 时，请注意以下事项：
 
@@ -205,13 +206,13 @@ export default defineConfig({
 modern.config.local.*
 ```
 
-## 合并多份配置
+### 合并多份配置
 
 在某些情况下，你可能需要将多份配置合并为一份配置，此时你可以使用 `mergeConfig` 工具函数来合并多个配置。
 
 `mergeConfig` 函数接受一个数组作为参数，数组中的每一项都是一个配置对象，`mergeConfig` 会将数组中的每一项配置对象进行深层合并，自动将多个函数项合并为数组，最终返回一个合并后的配置对象。
 
-### 示例
+#### 示例
 
 ```ts title="modern.config.ts"
 import { mergeConfig } from '@modern-js/app-tools';
@@ -249,7 +250,7 @@ const mergedConfig = {
 };
 ```
 
-## 配置类型定义
+### 配置类型定义
 
 Modern.js 导出了 `AppUserConfig` 类型，对应 Modern.js 配置对象的类型：
 
@@ -274,3 +275,25 @@ const config: AppUserConfig<'rspack'> = {
   },
 };
 ```
+
+## 运行时配置
+
+运行时配置的详细信息可以参考 [Runtime 配置介绍](/configure/app/runtime/0-intro.html)。
+
+:::tip
+如果当前的 Runtime 配置需要在编译时和运行时同时使用，请将相关配置参数添加到插件注册的位置。
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+import { statePlugin } from '@modern-js/plugin-state';
+
+export default defineConfig({
+  plugins: [
+    statePlugin({
+      /** 在此处添加参数 */
+    }),
+  ],
+});
+```
+
+:::

package/docs/zh/guides/basic-features/render/_meta.json

@@ -1 +1 @@
-["ssr", "streaming-ssr", "ssr-cache", "ssg"]
+["ssr", "streaming-ssr", "ssr-cache", "ssg", "before-render"]