@modern-js/main-doc 2.69.7 → 3.0.0-alpha.1

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

@@ -1,15 +1,15 @@
 # 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.
+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.
+- **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
 
@@ -47,25 +47,29 @@ Modern.js provides three main plugin types, corresponding to different stages of
 A typical Modern.js plugin consists of the following key parts:
 
 ```ts
-import type { Plugin } from '@modern-js/plugin-v2';
+import type { Plugin } from '@modern-js/plugin';
 
 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
+  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: {},
+  registryHooks: {},
 
   // 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(() => { /* ... */ });
+    api.modifyRspackConfig(config => {
+      /* ... */
+    });
+    api.onPrepare(() => {
+      /* ... */
+    });
     // ... Other API calls
   },
 };
@@ -77,8 +81,8 @@ export default myPlugin;
 
 ##### `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.
+- 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.
@@ -86,28 +90,28 @@ The plugin names declared in `pre`, `post`, and `required` refer to this `name`
 
 ##### `setup`
 
--   Type: `(api: PluginAPI) => MaybePromise<void>`
--   Description: The main entry point for the plugin's logic.
+- 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.
+- 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.
+- 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.
+- 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.
+- 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.
@@ -123,6 +127,7 @@ If you need to explicitly declare that the plugins that the current plugin depen
 :::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>>`
@@ -134,104 +139,106 @@ The core of the Modern.js plugin system is its Hook model, which defines the com
 
 ### 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`.
+- **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';
+import { createAsyncHook } from '@modern-js/plugin';
 
 export type AfterPrepareFn = () => Promise<void> | void;
 export const onAfterPrepare = createAsyncHook<AfterPrepareFn>();
 
 // Register Hooks in the plugin
 const myPlugin = () => ({
-  name: "my-plugin",
+  name: 'my-plugin',
   registryHooks: {
     onAfterPrepare,
   },
-  setup: (api) => {
+  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) => {
+  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`.
+- **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';
+import { createSyncHook } from '@modern-js/plugin';
 
-type RouteObject = {/** TODO **/};
+type RouteObject = {
+  /** TODO **/
+};
 const modifyRoutes = createSyncHook<(routes: RouteObject[]) => RouteObject[]>();
 
 // Register Hooks in the plugin
 const myPlugin = () => ({
-  name: "my-plugin",
+  name: 'my-plugin',
   registryHooks: {
     modifyRoutes,
   },
-  setup: (api) => {
+  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) => {
+  name: 'my-plugin',
+  setup: api => {
+    api.modifyRoutes(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.
+- **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

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

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

@@ -1,6 +1,6 @@
 # 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.
+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.
 
 :::info
 
@@ -13,18 +13,18 @@ Runtime plugins need to be configured via the [`plugins`](/configure/app/runtime
 A typical Runtime Plugin looks like this:
 
 ```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 => {
     // Use the api to register hooks
-    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`:  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.
+- `name`: A unique identifier for the plugin.
+- `setup`: A function that receives an `api` object, which provides all available Runtime plugin APIs.
 
 ## 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**: Getting runtime configuration and hook functions.
+- **Lifecycle Hooks**: Executing custom logic at different stages of the application's rendering process.
 
 ### Information Retrieval
 
@@ -53,7 +52,7 @@ The Runtime Plugin API is primarily divided into the following categories:
 
 Gets the runtime configuration defined by the user in the `modern.runtime.ts` file.
 
--   **Usage**:
+- **Usage**:
 
 ```ts
 const config = api.getRuntimeConfig();
@@ -62,23 +61,25 @@ 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.
+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:**
+- **Type:**
 
 ```ts
 () => {
-  onBeforeRender: { call: (context: any) => Promise<void> };
+  onBeforeRender: {
+    call: (context: any) => Promise<void>;
+  }
   // Other hooks...
 };
 ```
 
--   **Usage:**
+- **Usage:**
 
 ```ts
 const hooks = api.getHooks();
@@ -89,63 +90,65 @@ await hooks.onBeforeRender.call(myContext);
 
 #### `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.
+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:**
+- **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.
+  ```ts
+  type OnBeforeRenderFn<RuntimeContext> = (
+    context: RuntimeContext,
+  ) => Promise<void> | void;
+  ```
 
--   **Usage:**
+  `RuntimeContext` contains contextual information about the current request, such as the request object, response object, etc.
 
-    ```ts
-    api.onBeforeRender(async (context) => {
-      const data = await fetchData(context.req);
-      context.data = data; // Add the data to the context
-    });
-    ```
+- **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.
+- 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.
+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:**
+- **Type:**
 
-    ```ts
-    type WrapRootFn = (
-      App: React.ComponentType<any>
-    ) => React.ComponentType<any>;
-    ```
+  ```ts
+  type WrapRootFn = (App: React.ComponentType<any>) => React.ComponentType<any>;
+  ```
 
--   **Usage:**
+- **Usage:**
 
-    ```ts
-    api.wrapRoot((App) => {
-      const AppWrapper = (props) => {
-        return (
-          <MyGlobalProvider>
-            <Layout>
-              <App {...props} /> {/* Make sure to pass props */}
-            </Layout>
-          </MyGlobalProvider>
-        );
-      };
-      return AppWrapper;
-    });
-    ```
-:::warning
+      ```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.
+- **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.
 
 :::
 
@@ -156,12 +159,12 @@ Allows you to wrap the application's root component with a custom React componen
 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
-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 => {
@@ -176,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/en/plugin/server-plugins/_meta.json

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