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

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

@@ -1,35 +1,37 @@
----
-sidebar_position: 0
----
+# Configuration
 
-# Configuring Modern.js
+There are three types of configurations in Modern.js: Compile configuration, Runtime configuration, and Server Runtime configuration.
 
-There are two configurations in the Modern.js, a compile configuration and a server runtime configuration.
+**Compile configuration** can be configured in two locations:
 
-The compile configuration can be configured in two places:
-
-- `modern.config.(ts|js|mjs)` file in the root path
-- `package.json` file
+- The `modern.config.(ts|js|mjs)` file at the root path
+- The `package.json` file
 
 :::info
-Configurations in both `package.json` and `modern.config.ts` file are not supported for the same configuration. Configuration in `modern.config.ts` is recommended.
+Modern.js does not support configuring the same configuration item in both `package.json` and `modern.config.ts` simultaneously. It is recommended to configure it in `modern.config.ts`. If Modern.js detects conflicts due to duplicate configurations, it will throw a warning.
 :::
 
-Server runtime configuration can be configured in the `modern.server-runtime.config.(ts|js|mjs)` file in the root path.
+**Runtime configuration** can be configured in the `src/modern.runtime.(ts|js|mjs)` file.
+
+{/* TODO server 配置文件更新 */}
+**Server Runtime configuration** can be configured in the `modern.server-runtime.config.(ts|js|mjs)` file in the root path.
+
+
+## Compile Configuration
 
-## Configure in the configuration file
+### Configuring in Configuration Files
 
-Modern.js configuration files are defined in the root path of the project, and supports `.ts`, `.js` and `.mjs` formats:
+The configuration files for Modern.js are defined in the root directory of the project and support `.ts`, `.js`, and `.mjs` formats:
 
 - `modern.config.ts`
 - `modern.config.js`
 - `modern.config.mjs`
 
-### modern.config.ts (recommended)
+#### modern.config.ts (Recommended)
 
-We recommend using configuration files in `.ts` format, which provides friendly TypeScript type hints to help you avoid configuration errors.
+We recommend using the `.ts` format for configuration files as it provides friendly TypeScript type hints, helping you avoid errors in the configuration.
 
-Import the `defineConfig` tool function from `@modern-js/app-tools`, which will help you with configuration type derivation and type completion:
+Import the `defineConfig` utility function from `@modern-js/app-tools`, which will assist you with type inference and type completion for the configuration:
 
 ```ts title="modern.config.ts"
 import { defineConfig } from '@modern-js/app-tools';
@@ -43,18 +45,18 @@ export default defineConfig({
 });
 ```
 
-When using Rspack as the bundler, due to some differences in configuration types between webpack and Rspack, you need to specify `<'rspack'>` generic type for `defineConfig`:
+When using Rspack as the bundler, due to some differences in configuration types between webpack and Rspack, you need to specify the `<'rspack'>` generic for `defineConfig`:
 
 ```diff title=modern.config.ts
 - export default defineConfig({
 + export default defineConfig<'rspack'>({
-   //...
+  // ...
 });
 ```
 
-### modern.config.js
+#### modern.config.js
 
-If you are developing a non-TypeScript project, you can use the configuration file in `.js` format:
+If you are developing a non-TypeScript project, you can use the `.js` format for the configuration file:
 
 ```js title="modern.config.js"
 export default {
@@ -66,7 +68,7 @@ export default {
 };
 ```
 
-You can also configure depending on your environment with `process.env.NODE_ENV`:
+You can also configure different settings based on the environment using `process.env.NODE_ENV`:
 
 ```js title="modern.config.js"
 export default {
@@ -76,9 +78,9 @@ export default {
 };
 ```
 
-### Export Configuration Function
+#### Exporting Configuration Functions
 
-Modern.js supports exporting a function in the configuration file, and you can dynamically compute the configuration in the function and return it to Modern.js.
+Modern.js supports exporting a function in the configuration file, where you can dynamically compute the configuration and return it to Modern.js.
 
 ```js title="modern.config.js"
 import { defineConfig } from '@modern-js/app-tools';
@@ -92,16 +94,16 @@ export default defineConfig(({ env, command }) => ({
 }));
 ```
 
-This function takes the following parameters:
+This function accepts the following parameters:
 
-- `env`: same as the value of `process.env.NODE_ENV`.
+- `env`: Corresponds to the value of `process.env.NODE_ENV`.
   - When running `modern dev` or `modern start`, the value of `env` is `development`.
   - When running `modern build` or `modern serve`, the value of `env` is `production`.
-- `command`: corresponds to the currently running command, such as `dev`, `start`, `build`, `serve`.
+- `command`: Corresponds to the current command being run, such as `dev`, `start`, `build`, or `serve`.
 
-### Export Async Function
+#### Exporting Asynchronous Functions
 
-Modern.js also supports exporting an asynchronous function in the configuration file, you can perform some asynchronous operations in the function:
+Modern.js also supports exporting an asynchronous function in the configuration file, allowing you to perform some asynchronous operations:
 
 ```js title="modern.config.js"
 import { defineConfig } from '@modern-js/app-tools';
@@ -117,11 +119,11 @@ export default defineConfig(async ({ env, command }) => {
 });
 ```
 
-### Specify the Configuration File
+#### Specifying Configuration Files
 
-You can specify the name of the configuration file using the `--config` option.
+The Modern.js command line supports specifying the name of the configuration file using the `--config` option.
 
-For example, if you need to use the `modern.prod.config.js` file when running `build`, you can add the following scripts to `package.json`:
+For example, if you need to use the `modern.prod.config.js` file when executing the `build` command, you can add the following configuration in `package.json`:
 
 ```json title="package.json"
 {
@@ -132,15 +134,15 @@ For example, if you need to use the `modern.prod.config.js` file when running `b
 }
 ```
 
-You can also abbreviate the `--config` option to `-c`:
+You can also abbreviate the `--config` option as `-c`:
 
 ```bash
 $ modern build -c modern.prod.config.js
 ```
 
-## Configure in package.json (not recommended)
+### Configuring in package.json (Not Recommended)
 
-In addition to configuration files, configuration options can also be set the `modernConfig` field in the `package.json`, such as:
+In addition to configuration files, you can also set configuration items under the `modernConfig` field in `package.json`, such as:
 
 ```json title="package.json"
 {
@@ -154,20 +156,20 @@ In addition to configuration files, configuration options can also be set the `m
 }
 ```
 
-Due to the limitation of the JSON file format, only simple types such as numbers, strings, boolean values, arrays, etc. can be defined in `package.json`. When we need to set the value of the function type, it is recommended to do so in the Modern.js configuration file.
+Due to the limitations of the JSON file format, only simple types such as numbers, strings, booleans, and arrays can be defined in `package.json`. When we need to set function-type values, it is recommended to do so in the Modern.js configuration file.
 
-### Note
+#### Notes
 
-- It is not recommended to use both `package.json` and `modern.config.t[j]s` for configuration. If both are used and a configuration conflict occurs, Modern.js will prompt error on the command line.
-- `@modern-js/runtime` exports the [defineConfig](/apis/app/runtime/app/define-config) API of the same name, please pay attention to the distinction.
+- It is not recommended to use both `package.json` and `modern.config.js` for configuration simultaneously. If both are used and conflicts arise, Modern.js will prompt an error in the command line.
+- The `@modern-js/runtime` exports a similarly named [defineConfig](/apis/app/runtime/app/define-config) API, so please be careful to distinguish between them.
 
-## Debug configuration locally
+### Local Debugging Configuration
 
-To facilitate local debugging configuration locally, Modern.js supports creating `modern.config.local.(ts|js|mjs)` files in the root directory of the project to override `modern.config.(ts|js|mjs)` configurations.
+To facilitate local debugging of configurations, Modern.js supports creating a `modern.config.local.(ts|js|mjs)` file in the root directory to override the configuration options in `modern.config.(ts|js|mjs)`.
 
-### Example
+#### Example
 
-For example, the port number is configured as `3000` in `modern.config.ts`:
+For example, if the `modern.config.ts` file in your project is configured with a port number of `3000`:
 
 ```ts title="modern.config.ts"
 import { defineConfig } from '@modern-js/app-tools';
@@ -179,7 +181,7 @@ export default defineConfig({
 });
 ```
 
-If you need to change the port number to `3001` to debugging locally, but you don't want to change the `modern.config.ts` file of the current project, you can create a `modern.config.local.ts` file and add the following configuration:
+If you need to change the port number to `3001` for local debugging but do not want to modify the current project's `modern.config.ts` file, you can create a `modern.config.local.ts` file and add the following configuration:
 
 ```ts title="modern.config.local.ts"
 import { defineConfig } from '@modern-js/app-tools';
@@ -191,52 +193,52 @@ export default defineConfig({
 });
 ```
 
-The configuration in the `modern.config.local.ts` file will be deep merged with the configuration in `modern.config.ts` and override the configurations in `modern.config.ts`, so `server.port` will be is overridden by `3001`.
+The configuration in the `modern.config.local.ts` file will be deeply merged with the configuration in `modern.config.ts`, overriding the options in `modern.config.ts`, so `server.port` will be changed to `3001`.
 
-### Note
+#### Notes
 
 When using `modern.config.local.ts`, please note the following:
 
-- The `modern.config.local.ts` file is only loaded when running `modern dev` or `modern start` commands, and will not be loaded when running `modern build`.
-- The `modern.config.local.ts` file overrides not only over `modern.config.ts`, but also the `modernConfig` field in `package.json`.
-- As `modern.config.local.ts` is only used for local debugging, it is not recommended to commit it to the repository, please ensure that the project's `.gitignore` file contains `modern.config.local.ts`.
+- The `modern.config.local.ts` file will only be loaded when executing the `modern dev` or `modern start` commands and will not be loaded during `modern build`.
+- The priority of the `modern.config.local.ts` file is higher than both `modern.config.ts` and the `modernConfig` field in `package.json`.
+- Since `modern.config.local.ts` is only used for local debugging, it is not recommended to commit it to the code repository. Ensure that the project's `.gitignore` file includes `modern.config.local.ts` and similar files.
 
-```bash title=".gitingore"
+```bash title=".gitignore"
 modern.config.local.*
 ```
 
-## Merge Multiple Configurations
+### Merging Multiple Configurations
 
-In some cases, you may need to merge multiple configurations into one configuration. You can use the `mergeConfig` util to merge multiple configurations.
+In some cases, you may need to merge multiple configurations into one. You can use the `mergeConfig` utility function to merge multiple configurations.
 
-The `mergeConfig` function accepts an array as a parameter, and each item in the array is a configuration object. `mergeConfig` will deeply merge each configuration object in the array, automatically merge multiple functions into an array, and returns a merged configuration object.
+The `mergeConfig` function accepts an array as a parameter, where each item in the array is a configuration object. `mergeConfig` will deeply merge each configuration object in the array, automatically merging multiple function items into an array, and finally returning a merged configuration object.
 
-### Example
+#### Example
 
 ```ts title="modern.config.ts"
 import { mergeConfig } from '@modern-js/app-tools';
 
 const config1 = {
-   dev: {
-     port: 3000,
-   },
-   tools: {
-     postcss: () => console. log('config1');
-   },
+  dev: {
+    port: 3000,
+  },
+  tools: {
+    postcss: () => console.log('config1');
+  },
 };
 const config2 = {
-   dev: {
-     port: 3001,
-   },
-   tools: {
-     postcss: () => console. log('config2');
-   },
+  dev: {
+    port: 3001,
+  },
+  tools: {
+    postcss: () => console.log('config2');
+  },
 };
 
 const mergedConfig = mergeConfig([config1, config2]);
 ```
 
-In the above example, the merged configuration object is:
+In the above example, the merged configuration object will be:
 
 ```ts
 const mergedConfig = {
@@ -249,9 +251,9 @@ const mergedConfig = {
 };
 ```
 
-## Configuration Type
+### Configuration Type Definitions
 
-Modern.js exports `AppUserConfig` type, which corresponds to the type of Modern.js configuration object:
+Modern.js exports the `AppUserConfig` type, which corresponds to the type of the Modern.js configuration object:
 
 ```ts title="modern.config.ts"
 import type { AppUserConfig } from '@modern-js/app-tools';
@@ -263,7 +265,7 @@ const config: AppUserConfig = {
 };
 ```
 
-When using Rspack as the bundler, due to some differences in configuration types between webpack and Rspack, you need to specify `<'rspack'>` generic type for `defineConfig`:
+When using Rspack as the bundler, due to some differences in configuration types between webpack and Rspack, you need to specify the `<'rspack'>` generic for `AppUserConfig`:
 
 ```ts title="modern.config.ts"
 import type { AppUserConfig } from '@modern-js/app-tools';
@@ -274,3 +276,25 @@ const config: AppUserConfig<'rspack'> = {
   },
 };
 ```
+
+## Runtime Configuration
+
+For detailed information on runtime configuration, please refer to the [Introduction to Runtime Configuration](/configure/app/runtime/0-intro.html).
+
+:::tip
+If the current Runtime configuration needs to be used both at compile time and runtime, please add the relevant configuration parameters at the plugin registration location.
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+import { statePlugin } from '@modern-js/plugin-state';
+
+export default defineConfig({
+  plugins: [
+    statePlugin({
+      /** Add parameters here */
+    }),
+  ],
+});
+```
+
+:::

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

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

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

@@ -0,0 +1,115 @@
+# Render Preprocessing
+
+In certain scenarios, applications need to perform preprocessing operations before rendering. Modern.js recommends using **[Runtime Plugins](/plugin/introduction.html#runtime-plugins)** to implement this type of logic.
+
+## Defining a Runtime Plugin
+
+```ts
+import type { RuntimePluginFuture } from '@modern-js/runtime';
+
+const myRuntimePlugin = (): RuntimePluginFuture => ({
+  name: 'my-runtime-plugin',
+  setup: (api) => {
+    api.onBeforeRender((context) => {
+      // Logic to execute before rendering
+      console.log('Before rendering:', context);
+    });
+  },
+});
+
+export default myRuntimePlugin;
+```
+
+## Registering the Plugin
+
+Register the plugin in your project's `src/modern.runtime.ts` file:
+
+```ts
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import myRuntimePlugin from './plugins/myRuntimePlugin';
+
+export default defineRuntimeConfig({
+  plugins: [myRuntimePlugin()],
+});
+```
+
+## Use Case -- Global Data Injection
+
+Through the `context` parameter of the `onBeforeRender` hook, you can inject global data into your application. Application components can access this data using the `useRuntimeContext` Hook.
+
+:::info
+
+This feature is particularly useful in the following scenarios:
+* Applications requiring page-level preliminary data
+* Custom data injection workflows
+* Framework migration scenarios (e.g., migrating from Next.js)
+
+:::
+
+**Defining a Data Injection Plugin**
+
+```ts
+import type { RuntimePluginFuture } from '@modern-js/runtime';
+
+const dataInjectionPlugin = (): RuntimePluginFuture => ({
+  name: 'data-injection-plugin',
+  setup: api => {
+    api.onBeforeRender(context => {
+      // Inject data into the context
+      context.message = 'Hello World';
+    });
+  },
+});
+
+export default dataInjectionPlugin;
+```
+
+**Using Injected Data in Components**
+
+```tsx
+import { useRuntimeContext } from '@modern-js/runtime';
+
+export default function MyComponent() {
+  const context = useRuntimeContext();
+  const { message } = context;
+
+  return <div>{message}</div>;
+}
+```
+
+**Using with SSR**
+
+In SSR scenarios, the browser can access data injected via `onBeforeRender` during server-side rendering. Developers can decide whether to re-fetch data on the browser side to override server data based on their requirements.
+
+```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') {
+        // Set data during server-side rendering
+        context.message = 'Hello World By Server';
+      } else {
+        // Check data during client-side rendering
+        if (!context.message) {
+          // If server data is not available, set client data
+          context.message = 'Hello World By Client';
+        }
+      }
+    });
+  },
+});
+
+export default dataInjectionPlugin;
+```
+
+## Compatibility Notes
+
+In earlier versions of Modern.js, it was possible to add render preprocessing logic through the `init` hook in `routes/layout.tsx` and the `App.init` method. These approaches are still **supported**, but we **strongly recommend** implementing with Runtime plugins instead.
+
+:::warning
+
+In future versions, the `init` hook in `routes/layout.tsx` and the `App.init` method will be gradually **deprecated**. We recommend migrating to the Runtime plugin approach as soon as possible.
+:::

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

@@ -480,101 +480,6 @@ The `prefetch` attribute has three optional values:
 
 :::
 
-
-## Runtime Configuration
-
-{/* Todo Move to runtime configuration chapter */}
-
-In the root `<Layout>` component (`routes/layout.ts`), you can dynamically define runtime configuration:
-
-```tsx title="src/routes/layout.tsx"
-// Define runtime configuration
-import type { AppConfig } from '@modern-js/runtime';
-
-export const config = (): AppConfig => {
-  return {
-    router: {
-      createRoutes() {
-        return [
-          {
-            path: 'modern',
-            element: <div>modern</div>,
-          },
-        ];
-      },
-    },
-  };
-};
-```
-
-## Pre-render Hooks
-
-{/* Todo Move to runtime configuration chapter */}
-
-In some scenarios, you need to perform certain actions before the application renders. You can define the `init` hook in `routes/layout.tsx`, which will be executed both on the client and server. A basic example is shown below:
-
-```ts title="src/routes/layout.tsx"
-import type { RuntimeContext } from '@modern-js/runtime';
-
-export const init = (context: RuntimeContext) => {
-  // do something
-};
-```
-
-With the `init` hook, you can mount some global data that can be accessed elsewhere in the application via the `runtimeContext` variable:
-
-:::note
-This feature is very useful when applications require pre-rendered data, custom data injection, or framework migration (e.g., 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>;
-};
-```
-
-With SSR, the browser can obtain the data returned by `init` during SSR. Developers can decide whether to re-fetch the data on the browser side to override the SSR data. For example:
-
-```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 the expected data is not obtained
-    if (!data.message) {
-      return {
-        message: 'Hello World By Client',
-      };
-    }
-  }
-};
-```
-
 <Motivation />
 
 ## FAQ

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

@@ -14,9 +14,9 @@ Through this chapter you can learn:
 
 The routing modes of the current project are divided into the following three types:
 
-- File-based routing (`router: true` and file-based)
-- Self-Controlled routing (`router: true` and create `BrowserRouter`)
-- Other (`router: false` and independent installation of `react-router-dom` in the project)
+- [Conventional Routing](/guides/concept/entries.html#conventional-routing)
+- [Self-controlled Routing](/guides/concept/entries.html#self-controlled-routing)
+- Other (independent installation of `react-router-dom` in the project)
 
 First, clarify the routing mode of the main application [create a file-based routing main App](#file-based-routing-main-app) or [create a self-controlled main App](#self-controlled-main-app)
 
@@ -198,7 +198,6 @@ export default defineConfig({
   },
   runtime: {
     router: true,
-    state: true,
   },
   deploy: {
     microFrontend: true,
@@ -245,7 +244,6 @@ export default defineConfig({
   },
   runtime: {
     router: true,
-    state: true,
   },
   deploy: {
     microFrontend: true,

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

@@ -35,8 +35,10 @@ import MicroRuntimeConfig from '@site-docs-en/components/micro-runtime-config';
 
 This function allows you to pull a list of remote child applications and register them with the runtime framework:
 
-```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/en/guides/topic-detail/model/auto-actions.mdx

@@ -1,7 +1,3 @@
----
-sidebar_position: 6
-title: Automatically Actions
----
 # Automatically Generated Actions
 
 In the [Quick Start](/guides/topic-detail/model/quick-start), we implemented the simplest counter model, which still required 10 lines of code. In fact, Modern.js supports automatically generating commonly used actions based on the declared `state` type, which reduces the amount of boilerplate code. The currently supported types are:

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

@@ -1,8 +1,3 @@
----
-sidebar_position: 4
-title: Derived State
----
-
 # Derived State
 
 In some scenarios, components need to perform further calculations on the State in Model before they can be used in the components. This logic can be directly written in the component or implemented through derived states in Model. Derived states are defined under the `computed` field in the Model. Depending on the dependencies of the Model and the return type, there are three ways to define derived states.

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

@@ -1,7 +1,3 @@
----
-sidebar_position: 2
-title: Define Model
----
 # Define a Model
 
 In the previous section, we demonstrated how to create a Model for a simple counter application. In this section, we will provide a detailed introduction on how to create a Model.

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

@@ -1,8 +1,3 @@
----
-sidebar_position: 13
-title: FAQ
----
-
 # FAQ
 
 ## Browser Compatibility

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

@@ -1,8 +1,3 @@
----
-sidebar_position: 5
-title: Management Effect
----
-
 # Management Effect
 
 The actions in the model must be pure functions and cannot have any side effects during execution. However, in real-world scenarios, we often encounter many side effects, such as: requesting data from an HTTP API to obtain state data, or modifying `localStorage` or sending events while updating the state. In Reduck, side effects are managed through the model's `effects` function.

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

@@ -1,8 +1,3 @@
----
-sidebar_position: 7
-title: Model Communication
----
-
 # Model Communication
 
 Model communication refers to communication between different Models, as well as communication between Effects and Actions within the same Model.

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

@@ -1,7 +1,3 @@
----
-sidebar_position: 8
-title: Performance Optimization
----
 # Performance Optimization
 
 Reduck has already done a lot of performance optimization work internally, so performance issues generally do not need to be considered. However, when performance is more sensitive, or when encountering performance issues, you can consider more targeted performance optimization from the following three aspects.