@modern-js/main-doc 2.65.5 → 2.66.0

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

@@ -0,0 +1,237 @@
+# Plugin System
+
+Modern.js adopts a highly extensible, plugin-based architecture, where its core functionalities and extended capabilities are implemented through plugins.  The plugin system not only ensures the framework's flexibility but also provides developers with powerful customization options. This document focuses on how to write Modern.js plugins, helping you quickly get started with plugin development.
+
+## Core Concept: Everything is a Plugin
+
+Modern.js adheres to the design philosophy of "everything is a plugin," modularizing the framework's various functional components and assembling and extending them through plugins. This design brings several advantages, including:
+
+-   **High Cohesion, Low Coupling:** Each functional module is independently developed, tested, and maintained, reducing system complexity.
+-   **Flexible and Extensible:** Users can easily customize the framework's behavior by writing or combining plugins without modifying the core code.
+-   **Easy to Reuse:** Plugins can be shared across projects, improving development efficiency.
+-   **Progressive Enhancement:** Plugins are introduced on demand, without the complexity of carrying all functionalities from the start.
+
+## Plugin Types and Use Cases
+
+Modern.js provides three main plugin types, corresponding to different stages of application development:
+
+**CLI Plugins:**
+    -   **Active Stage:** Build time (when executing the `modern` command).
+    -   **Typical Scenarios:**
+        -   Extending command-line tools.
+        -   Modifying build configurations.
+        -   Listening for file changes.
+        -   Controlling the build process.
+    -   **Configuration Method:** The `plugins` field in `modern.config.ts`.
+
+**Runtime Plugins:**
+    -   **Active Stage:** Application runtime (browser/Node.js environment).
+    -   **Typical Scenarios:**
+        -   Initializing global state or services.
+        -   Encapsulating React Higher-Order Components (HOCs).
+        -   Intercepting or modifying routing behavior.
+        -   Controlling the rendering process.
+    -   **Configuration Method:** The `plugins` field in `src/modern.runtime.ts`.
+
+{/* **Server Plugins:**
+    -   **Active Stage:** Server request processing stage.
+    -   **Typical Scenarios:**
+        -   Adding custom middleware.
+        -   Extending server-side APIs.
+        -   Customizing SSR logic.
+        -   Integrating with backend frameworks.
+    -   **Configuration Method:** The `plugins` field in `server/modern.server.ts`. */}
+
+## Plugin Structure
+
+A typical Modern.js plugin consists of the following key parts:
+
+```ts
+import type { Plugin } from '@modern-js/plugin-v2';
+
+const myPlugin: Plugin = {
+  name: 'my-awesome-plugin', // The unique identifier of the plugin (required)
+
+  // Plugin dependencies and execution order (optional)
+  pre: [],    // List of plugin names to execute before this plugin, defaults to an empty array
+  post: [],   // List of plugin names to execute after this plugin, defaults to an empty array
+  required: [],// List of required plugins; if a dependent plugin is not registered, an error will be thrown, defaults to an empty array
+  usePlugins: [], // List of plugin instances used internally, defaults to an empty array
+
+  // Register new Hooks (optional)
+  registryHook: {},
+
+  // The entry function of the plugin (required)
+  setup(api) {
+    // The core logic of the plugin, calling plugin APIs through the api object
+    api.modifyWebpackConfig(config => { /* ... */ });
+    api.onPrepare(() => { /* ... */ });
+    // ... Other API calls
+  },
+};
+
+export default myPlugin;
+```
+
+**Field Descriptions:**
+
+##### `name`
+
+-   Type: `string`
+-   Description:  Identifies the name of the plugin.  This name must be unique within the plugin system; otherwise, the plugin will fail to load.
+
+:::info
+The plugin names declared in `pre`, `post`, and `required` refer to this `name` field.
+:::
+
+##### `setup`
+
+-   Type: `(api: PluginAPI) => MaybePromise<void>`
+-   Description: The main entry point for the plugin's logic.
+
+###### `api`
+
+-   Type: `PluginAPI`
+-   Description: The plugin's API, containing the Hooks and utility functions supported by the plugin.
+
+##### `pre`
+
+-   Type: `string[]`
+-   Description: Used to insert the plugin execution order. Plugins declared in `pre` will be executed before this plugin.
+
+##### `post`
+
+-   Type: `string[]`
+-   Description: Used to determine the plugin execution order. Plugins declared in `post` will be executed after this plugin.
+
+##### `required`
+
+-   Type: `string[]`
+-   Description: Other plugins that this plugin depends on. Before running, it will check if the dependent plugins are registered.
+
+:::info
+If unregistered plugin names are configured in `pre` or `post`, these plugin names will be **automatically ignored** and will not affect the execution of other plugins.
+
+If you need to explicitly declare that the plugins that the current plugin depends on must exist, you need to use the `required` field.
+:::
+
+##### `usePlugins`
+
+- Type: `Plugin`
+- Description: Actively register other plugins of the same type within the plugin.
+
+:::info
+Plugins declared in `usePlugins` are executed before the current plugin by default. To execute them after, use the `post` declaration.
+:::
+##### `registryHooks`
+
+- Type: `Record<string, PluginHook<(...args: any[]) => any>>`
+- Description: Extend the currently supported Hook functions to implement custom functionality.
+
+## Plugin Hook Model
+
+The core of the Modern.js plugin system is its Hook model, which defines the communication mechanism between plugins. Modern.js mainly provides two types of Hooks:
+
+### Async Hook
+
+-   **Characteristics:**
+    -   Hook functions are executed asynchronously, supporting `async/await`.
+    -   The return value of the previous Hook function is passed as the first argument to the next Hook function.
+    -   Finally returns the return value of the last Hook function.
+-   **Use Cases:** Scenarios involving asynchronous operations (such as network requests, file reading/writing, etc.).
+-   **Creation Method:** Created using `createAsyncHook`.
+
+Example:
+
+```ts
+// Define Hooks
+import { createAsyncHook } from '@modern-js/plugin-v2';
+
+export type AfterPrepareFn = () => Promise<void> | void;
+export const onAfterPrepare = createAsyncHook<AfterPrepareFn>();
+
+// Register Hooks in the plugin
+const myPlugin = () => ({
+  name: "my-plugin",
+  registryHooks: {
+    onAfterPrepare,
+  },
+  setup: (api) => {
+    api.onPrepare(async () => {
+      // Use the registered Hooks in the plugin
+      const hooks = api.getHooks();
+      await hooks.onAfterPrepare.call();
+    });
+  }
+});
+
+// Use Hook in other plugins
+const myPlugin2 = () => ({
+  name: "my-plugin-2",
+  setup: (api) => {
+    api.onAfterPrepare(async () => {
+      // TODO
+    });
+  }
+})
+```
+
+### Sync Hook (Synchronous Hook)
+
+-   **Characteristics:**
+    -   Hook functions are executed synchronously.
+    -   The return value of the previous Hook function is passed as the first argument to the next Hook function.
+    -   Finally returns the return value of the last Hook function.
+-   **Use Cases:** Scenarios where data needs to be modified synchronously (such as modifying configurations, routes, etc.).
+-   **Creation Method:** Created using `createSyncHook`.
+
+Example:
+
+```ts
+// Define Hooks
+import { createSyncHook } from '@modern-js/plugin-v2';
+
+type RouteObject = {/** TODO **/};
+const modifyRoutes = createSyncHook<(routes: RouteObject[]) => RouteObject[]>();
+
+// Register Hooks in the plugin
+const myPlugin = () => ({
+  name: "my-plugin",
+  registryHooks: {
+    modifyRoutes,
+  },
+  setup: (api) => {
+    api.onPrepare(async () => {
+      const routes = {};
+      // Use registered Hooks in the plugin
+      const hooks = api.getHooks();
+      const routesResult = hooks.modifyRoutes.call(routes);
+    });
+  }
+});
+
+// Other plugins use Hooks
+const myPlugin2 = () => ({
+  name: "my-plugin",
+  setup: (api) => {
+    api.modifyRoutes(async (routes) => {
+      // Modify routes
+      return routes;
+    });
+  }
+});
+```
+
+## Plugin Development Best Practices
+
+-   **Single Responsibility:** Each plugin should focus on implementing a specific, cohesive function. Avoid creating plugins with complex functionalities and unclear responsibilities.
+-   **Naming Conventions:** Plugin names should be clear, concise, and follow certain naming conventions (such as `plugin-xxx` or `@scope/plugin-xxx`).
+-   **Type Safety:** Make full use of TypeScript's type system to ensure the type safety of the plugin API and reduce runtime errors.
+-   **Comprehensive Documentation:** Write clear documentation for the plugin, including API descriptions, usage examples, configuration explanations, and change logs.
+-   **Thorough Testing:** Conduct unit tests and integration tests on the plugin to ensure its stability, reliability, and compatibility in various scenarios.
+-   **Minimize Side Effects:** Plugins should minimize modifications to the external environment (such as global variables, file systems, etc.) to maintain the plugin's independence and portability.
+-   **Error Handling:** Plugins should properly handle potential errors to prevent the entire application from crashing due to plugin exceptions.
+-   **Performance Optimization:** Pay attention to the performance impact of the plugin, avoid unnecessary calculations and resource consumption, especially in loops or frequently called Hooks.
+-   **Version Control:** Follow Semantic Versioning (SemVer) to ensure the backward compatibility of the plugin and facilitate user upgrades.
+
+Following these best practices can help you develop high-quality, easy-to-maintain, and easy-to-use Modern.js plugins.

package/docs/en/plugin/runtime-plugins/_meta.json

@@ -0,0 +1 @@
+["api", "life-cycle", "migration"]

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

@@ -0,0 +1,165 @@
+# Plugin API
+
+Modern.js's Runtime Plugins allow you to extend and modify the behavior of your application during its React code execution.  With Runtime Plugins, you can easily perform initialization tasks, implement React Higher-Order Component (HOC) wrapping, and more.
+
+## Plugin Structure
+
+A typical Runtime Plugin looks like this:
+
+```ts
+import type { RuntimePluginFuture } from '@modern-js/runtime';
+
+const myRuntimePlugin = (): RuntimePluginFuture => ({
+  name: 'my-runtime-plugin',
+  setup: (api) => {
+    // Use the api to register hooks
+    api.onBeforeRender((context) => {
+      console.log('Before rendering:', context);
+    });
+
+    api.wrapRoot((App) => {
+      return (props) => (
+        <MyContextProvider>
+          <App {...props} />
+        </MyContextProvider>
+      );
+    });
+  },
+});
+
+export default myRuntimePlugin;
+
+```
+
+-   `name`:  A unique identifier for the plugin.
+-   `setup`: The main logic of the plugin, which receives an `api` object as a parameter.  This `api` object is used to register hooks.
+
+## API Overview
+
+The Runtime Plugin API is primarily divided into the following categories:
+
+-   **Information Retrieval**:  Getting runtime configuration and hook functions.
+-   **Lifecycle Hooks**:  Executing custom logic at different stages of the application's rendering process.
+
+### Information Retrieval
+
+#### `api.getRuntimeConfig`
+
+Gets the runtime configuration defined by the user in the `modern.runtime.ts` file.
+
+-   **Usage**:
+
+```ts
+const config = api.getRuntimeConfig();
+console.log(config.myCustomSetting);
+```
+
+:::warning
+
+This method returns a *copy* of the user's configuration. Modifying the returned value will not affect the original configuration.
+:::
+
+#### `api.getHooks`
+
+Gets the hook functions that can be triggered manually.
+
+-   **Type:**
+
+```ts
+() => {
+  onBeforeRender: { call: (context: any) => Promise<void> };
+  // Other hooks...
+};
+```
+
+-   **Usage:**
+
+```ts
+const hooks = api.getHooks();
+await hooks.onBeforeRender.call(myContext);
+```
+
+### Lifecycle Hooks
+
+#### `api.onBeforeRender`
+
+Executes before the application renders (including both server-side rendering and client-side rendering).  You can use this hook to perform data prefetching, modify the rendering context, etc.
+
+-   **Type:**
+
+    ```ts
+    type OnBeforeRenderFn<RuntimeContext> = (context: RuntimeContext) => Promise<void> | void;
+    ```
+    `RuntimeContext` contains contextual information about the current request, such as the request object, response object, etc.
+
+-   **Usage:**
+
+    ```ts
+    api.onBeforeRender(async (context) => {
+      const data = await fetchData(context.req);
+      context.data = data; // Add the data to the context
+    });
+    ```
+
+:::warning
+
+- This hook executes before *every* render, so avoid performing long-running operations.
+- You can modify the `context` object in this hook, and the modified `context` will be passed to subsequent rendering processes.
+
+:::
+
+#### `api.wrapRoot`
+
+Allows you to wrap the application's root component with a custom React component.  This is commonly used to add global Providers, layout components, etc.
+
+-   **Type:**
+
+    ```ts
+    type WrapRootFn = (
+      App: React.ComponentType<any>
+    ) => React.ComponentType<any>;
+    ```
+
+-   **Usage:**
+
+    ```ts
+    api.wrapRoot((App) => {
+      const AppWrapper = (props) => {
+        return (
+          <MyGlobalProvider>
+            <Layout>
+              <App {...props} /> {/* Make sure to pass props */}
+            </Layout>
+          </MyGlobalProvider>
+        );
+      };
+      return AppWrapper;
+    });
+    ```
+:::warning
+
+-   **It is crucial to pass the `props` to the original `App` component**, otherwise, the application may not function correctly.
+-   The component returned by `wrapRoot` is recreated on every render, so avoid defining complex logic or state within it.
+
+:::
+
+## Advanced Usage
+
+### Combining Hooks
+
+You can combine multiple hooks to implement more complex functionality. For example, you can use `onBeforeRender` to fetch data and then use `wrapRoot` to pass the data to the entire application via Context:
+
+```ts
+api.onBeforeRender(async (context) => {
+  const data = await fetchData(context.req);
+  context.data = data;
+});
+
+api.wrapRoot((App) => {
+  return (props) => (
+    <DataContext.Provider value={props.data}>
+      <App {...props} />
+    </DataContext.Provider>
+  );
+});
+```

package/docs/en/plugin/runtime-plugins/life-cycle.mdx

@@ -0,0 +1,29 @@
+# Life Cycle
+
+import Mermaid from '@site/src/components/Mermaid';
+
+<Mermaid>
+{`
+flowchart TD
+    init{{"Runtime Initialization"}}
+    load_config(Load User Configuration File)
+    runtime_plugin(Load Runtime Plugins<br><sub>Plugins registered in the configuration file<br>Runtime plugins registered by CLI<br>Plugins used within plugins</sub>)
+    registry_hooks(Register Hooks Functions<br><sub>Execute the plugin setup function, register hooks defined in the plugin, and the logic in the plugin setup will also be executed here</sub>)
+
+    wrapRoot(wrapRoot<br><sub>The logic returned in wrapRoot will be executed when the component is rendered</sub>)
+    onBeforeRender(onBeforeRender)
+
+    init --> load_config
+    load_config --> runtime_plugin
+    runtime_plugin --> registry_hooks
+    registry_hooks --> wrapRoot
+    wrapRoot --> onBeforeRender
+
+    style init fill:#FDE68A,font-size:10px;
+    style load_config stroke-dasharray:5 5,fill:#86EFAC,font-size:10px;
+    style runtime_plugin stroke-dasharray:5 5,fill:#86EFAC,font-size:10px;
+    style registry_hooks stroke-dasharray:5 5,fill:#9CA3AF,font-size:10px;
+    style wrapRoot font-size:10px;
+    style onBeforeRender font-size:10px;
+`}
+</Mermaid>

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

@@ -0,0 +1,101 @@
+# Plugin Migration
+
+### Migration Background
+
+The Modern.js plugin system is constantly evolving.  To provide a clearer API and more powerful features, we've optimized the definition and usage of Runtime plugins. While the old plugin syntax is still partially compatible, we strongly recommend migrating according to this guide to take full advantage of the new plugin system.
+
+### Migration Steps Overview
+
+1.  **Update Plugin Type Definition:** Replace the `Plugin` type with `RuntimePluginFuture`.
+2.  **Adjust Hook Invocation:** Migrate from the `return hooks` pattern to direct `api.xxx` calls.
+3.  **Replace Changed APIs:** Refer to the detailed API mapping table and update your code.
+
+### Detailed Migration Steps
+
+#### Update Plugin Type Definition
+
+This is the first and most crucial step. It ensures that your plugin interacts correctly with the new plugin system.
+
+```typescript
+// Old Syntax
+import type { Plugin } from '@modern-js/runtime';
+
+const plugin: Plugin = { ... };
+
+// New Syntax
+import type { RuntimePluginFuture } from '@modern-js/runtime';
+
+const plugin: RuntimePluginFuture = { ... };
+```
+
+**Explanation:** The `RuntimePluginFuture` type is the standard definition for new plugins. It provides better type inference and a clearer API structure.
+
+#### Adjust Hook Invocation
+
+The new plugin system recommends using the `api` object to directly call Hooks. This approach is more intuitive and easier to maintain.
+
+```typescript
+// Old Syntax (return hooks)
+{
+  setup: () => ({
+    beforeRender({ req, res }) { /*...*/ }
+  })
+}
+
+// New Syntax (api.xxx)
+{
+  setup: api => {
+    api.onBeforeRender(({ req, res }) => { /*...*/ })
+  }
+}
+```
+
+**Explanation:** The `api` object provides all available Hooks and utility methods.
+
+#### Replace Changed APIs
+
+To maintain API consistency and clarity, we've adjusted the names of some APIs.  Additionally, the `hoc` and `init` Hooks have been removed. Please use the new Hooks as replacements. The table below lists all changed APIs and their old and new counterparts:
+
+| Old API       | New API           | Description                                                                                                                                                                                                                                                                                                 |
+| :------------ | :---------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `beforeRender` | `onBeforeRender`  | Executed before application rendering.                                                                                                                                                                                                                                                                        |
+| `hoc`         | `wrapRoot`        | **Important Change:** Used to wrap the root component, achieving the functionality of a Higher-Order Component (HOC).  Make sure to pass props to the original component.                                                                                                                                    |
+| `init`        | `onBeforeRender`  | **Important Change:**  Execute initialization logic before application rendering. This replaces the previous `init` hook. Use `onBeforeRender` to perform any setup or initialization tasks that were previously done in `init`.  This provides a single, consistent point for pre-rendering logic. |
+
+**Explanation:**
+- `onBeforeRender` replaces both the original `beforeRender` and `init`, used for pre-rendering logic and initialization, respectively.
+- `wrapRoot` replaces `hoc` and is used to implement higher-order component functionality.  It's crucial to pass props correctly when using `wrapRoot`.
+
+**`wrapRoot` Usage Example:**
+
+```typescript
+{
+  setup: api => {
+    api.wrapRoot((App) => {
+      const AppWrapper = (props) => {
+        // Ensure props are passed to the original component
+        return <Provider value={xx}><App {...props}/></Provider>;
+      };
+      return AppWrapper;
+    });
+  }
+}
+```
+
+### Frequently Asked Questions
+
+**Q: Will my plugin still work correctly after migration?**
+
+A: As long as you've correctly completed all the steps in this guide, your plugin should function properly. If you encounter any issues, please refer to the official Modern.js documentation or seek community support.
+
+**Q: Do I have to migrate my plugin immediately?**
+
+A: While the old plugin syntax remains partially compatible, we strongly recommend migrating as soon as possible. The new plugin system offers improved performance and richer functionality, making migration worthwhile in the long run.
+
+**Q: Where can I find more information about the new plugin system?**
+
+A: Please consult the official Modern.js documentation, especially the section on the plugin system. You can also refer to examples of other migrated plugins to understand best practices.
+
+### Summary
+
+With this detailed migration guide, we hope to help you smoothly transition your Runtime plugins to the new Modern.js plugin system. If you encounter any problems during the migration process, please don't hesitate to ask for assistance.

package/docs/en/plugin/server-plugins/api.mdx

@@ -0,0 +1,3 @@
+# Plugin API
+
+Comming soon...

package/docs/en/plugin/server-plugins/life-cycle.mdx

@@ -0,0 +1,3 @@
+# Life Cycle
+
+Comming soon...

package/docs/zh/community/blog/v2-release-note.mdx

@@ -132,7 +132,7 @@ Modern.js 可以划分为三个核心部分：**CLI 工具、服务端和运行
 
 在字节跳动内部，我们借助这些插件 API，结合公司内的基建和平台，封装出内部的企业级框架。如果你需要对 Modern.js 框架进行深度定制，也可以借助这些插件 API 来完成。
 
-> 如果你对 Modern.js 的插件系统感兴趣，请阅读 [「Modern.js - 自定义插件」](https://modernjs.dev/plugin/plugin-system/introduction.html)文档。
+> 如果你对 Modern.js 的插件系统感兴趣，请阅读 [「Modern.js - 自定义插件」](https://modernjs.dev/plugin/plugin-system.html)文档。
 
 ### 嵌套路由
 

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

@@ -9,7 +9,7 @@ sidebar_position: 9
 
 用于配置自定义的 Modern.js 框架插件。
 
-自定义插件的编写方式请参考 [如何编写插件](/plugin/plugin-system/implement)。
+自定义插件的编写方式请参考 [如何编写插件](/plugin/plugin-system)。
 
 ## 注意事项
 
@@ -33,7 +33,7 @@ Modern.js 中内置了三种不同的框架插件：
 
 默认情况下，自定义插件会按照 `plugins` 数组的顺序依次执行，Modern.js 内置插件的执行时机早于自定义插件。
 
-当插件内部使用了控制顺序的相关字段，比如 `pre`、`post` 时，会基于声明的字段对执行顺序进行调整，详见 [插件之间的关系](/plugin/plugin-system/relationship)。
+当插件内部使用了控制顺序的相关字段，比如 `pre`、`post` 时，会基于声明的字段对执行顺序进行调整，详见 [插件结构](/plugin/plugin-system)。
 
 ## 示例
 

package/docs/zh/configure/app/tools/esbuild.mdx

@@ -41,4 +41,4 @@ export default defineConfig({
 });
 ```
 
-完整配置项请参考 [esbuild 插件配置](/plugin/rsbuild-plugins/plugin-esbuild#配置)。
+完整配置项请参考 [esbuild 插件配置](/plugin/official/rsbuild-plugins/plugin-esbuild#配置)。

package/docs/zh/configure/app/tools/swc.mdx

@@ -108,4 +108,4 @@ export default defineConfig({
 });
 ```
 
-完整配置项请参考 [SWC 插件配置](/plugin/cli-plugins/plugin-swc.html#配置)。
+完整配置项请参考 [SWC 插件配置](/plugin/official/cli-plugins/plugin-swc.html#配置)。

package/docs/zh/plugin/_meta.json

@@ -1,19 +1,20 @@
 [
   "introduction",
+  "plugin-system",
   {
     "type": "dir",
-    "name": "plugin-system",
-    "label": "plugin-system",
-    "collapsed": true
+    "name": "cli-plugins",
+    "label": "cli-plugins"
   },
   {
     "type": "dir",
-    "name": "cli-plugins",
-    "label": "cli-plugins"
+    "name": "runtime-plugins",
+    "label": "runtime-plugins"
   },
   {
     "type": "dir",
-    "name": "rsbuild-plugins",
-    "label": "rsbuild-plugins"
+    "name": "official",
+    "label": "official-plugins",
+    "collapsed": true
   }
 ]

package/docs/zh/plugin/cli-plugins/_meta.json

@@ -1 +1 @@
-["plugin-tailwind", "plugin-bff", "plugin-ssg", "plugin-swc"]
+["api", "life-cycle", "migration"]