@modern-js/main-doc 2.67.3 → 2.67.5

package/docs/en/guides/advanced-features/web-server.mdx

@@ -2,7 +2,11 @@
 sidebar_position: 16
 ---
 
-# Custom Web Server
+# Custom Web Server (Not Recommended)
+
+:::warning
+Custom Web Server is compatible but no longer recommended. For extending Server capabilities, please refer to [Custom Server](/guides/advanced-features/custom-server.html). For migration guide, see [Migrate to the New Version of Custom Server](/guides/advanced-features/web-server.html#migrate-to-the-new-version-of-custom-server).
+:::
 
 Modern.js encapsulates most server-side capabilities required by projects, typically eliminating the need for server-side development. However, in certain scenarios such as user authentication, request preprocessing, or adding page skeletons, custom server-side logic may still be necessary.
 
@@ -96,3 +100,172 @@ Best practices when using Hooks:
 :::info
 For detailed API and more usage, see [Hook](/apis/app/runtime/web-server/hook).
 :::
+
+
+## Migrate to the New Version of Custom Server
+
+### Migration Background
+
+Modern.js Server is continuously evolving to provide more powerful features. We have optimized the definition and usage of middleware and Server plugins.
+While the old custom Web Server approach is still compatible, we strongly recommend migrating according to this guide to fully leverage the advantages of the new version.
+
+### Migration Steps
+
+1. Upgrade Modern.js version to x.67.5 or above.
+2. Configure middleware or plugins in `server/modern.server.ts` according to the new definition method.
+3. Migrate the custom logic in `server/index.ts` to middleware or plugins, and update your code with reference to the differences between `Context` and `Next`.
+
+### Context Differences
+
+In the new version, the middleware handler type is Hono's `MiddlewareHandler`, meaning the `Context` type is `Hono Context`. The differences from the old custom Web Server's `Context` are as follows:
+
+
+#### UnstableMiddleware
+
+
+```ts
+type Body = ReadableStream | ArrayBuffer | string | null;
+
+type UnstableMiddlewareContext<
+  V extends Record<string, unknown> = Record<string, unknown>,
+> = {
+  request: Request;
+  response: Response;
+  get: Get<V>;
+  set: Set<V>;
+  // Current Matched Routing Information
+  route: string;
+  header: (name: string, value: string, options?: { append?: boolean }) => void;
+  status: (code: number) => void;
+  redirect: (location: string, status?: number) => Response;
+  body: (data: Body, init?: ResponseInit) => Response;
+  html: (
+    data: string | Promise<string>,
+    init?: ResponseInit,
+  ) => Response | Promise<Response>;
+};
+```
+
+Differences between UnstableMiddleware Context and Hono Context:
+
+| UnstableMiddleware       | Hono                          | Description                                                                      |
+| :----------------------- | :---------------------------- | :------------------------------------------------------------------------ |
+| `c.request`              | `c.req.raw`                   | Refer to [HonoRequest raw](https://hono.dev/docs/api/request#raw) documentation         |
+| `c.response`             | `c.res`                       | Refer to [Hono Context res](https://hono.dev/docs/api/context#res) documentation       |
+| `c.route`                | `c.get('route')`              | Get application context information.                                                          |
+| `loaderContext.get`      | `honoContext.get`             | After injecting data using `c.set`, consume in dataLoader: the old version uses `loaderContext.get`, refer to the new version in [Plugin](/guides/advanced-features/custom-server.html#using-posture-2) example    |
+
+
+#### Middleware
+
+```ts
+type MiddlewareContext = {
+  response: {
+    set: (key: string, value: string) => void;
+    status: (code: number) => void;
+    getStatus: () => number;
+    cookies: {
+      set: (key: string, value: string, options?: any) => void;
+      clear: () => void;
+    };
+    raw: (
+      body: string,
+      { status, headers }: { status: number; headers: Record<string, any> },
+    ) => void;
+    locals: Record<string, any>;
+  };
+  request: {
+    url: string;
+    host: string;
+    pathname: string;
+    query: Record<string, any>;
+    cookie: string;
+    cookies: {
+      get: (key: string) => string;
+    };
+    headers: IncomingHttpHeaders;
+  };
+  source: {
+    req: IncomingMessage;
+    res: ServerResponse;
+  };
+};
+
+```
+
+Differences between Middleware `Context` and Hono `Context`:
+| UnstableMiddleware       | Hono                          | Description                                                                  |
+| :----------------------- | :---------------------------- | :--------------------------------------------------------------------------- |
+| `c.request.cookie`         | `c.req.cookie()`              | Refer to [Hono Cookie Helper](https://hono.dev/docs/helpers/cookie) documentation |
+| `c.request.pathname`       | `c.req.path`                  | Refer to [HonoRequest path](https://hono.dev/docs/api/request#path) documentation |
+| `c.request.url`            | -                             | Hono `c.req.url` provides the full request URL, calculate manually from URL |
+| `c.request.host`           | `c.req.header('Host')`        | Obtain host through header                                                  |
+| `c.request.query`          | `c.req.query()`               | Refer to [HonoRequest query](https://hono.dev/docs/api/request#query) documentation |
+| `c.request.headers`        | `c.req.header()`              | Refer to [HonoRequest header](https://hono.dev/docs/api/request#header) documentation |
+| `c.response.set`           | `c.res.headers.set`           | Example: `c.res.headers.set('custom-header', '1')`                          |
+| `c.response.status`        | `c.status`                    | Example: `c.status(201)`                                                    |
+| `c.response.cookies`       | `c.header`                    | Example: `c.header('Set-Cookie', 'user_id=123')`                            |
+| `c.response.raw`           | `c.res`                       | Refer to [Hono Context res](https://hono.dev/docs/api/context#res) documentation |
+
+#### Hook
+
+```ts
+type HookContext = {
+  response: {
+    set: (key: string, value: string) => void;
+    status: (code: number) => void;
+    getStatus: () => number;
+    cookies: {
+      set: (key: string, value: string, options?: any) => void;
+      clear: () => void;
+    };
+    raw: (
+      body: string,
+      { status, headers }: { status: number; headers: Record<string, any> },
+    ) => void;
+  };
+  request: {
+    url: string;
+    host: string;
+    pathname: string;
+    query: Record<string, any>;
+    cookie: string;
+    cookies: {
+      get: (key: string) => string;
+    };
+    headers: IncomingHttpHeaders;
+  };
+};
+
+type AfterMatchContext = HookContext & {
+  router: {
+    redirect: (url: string, status: number) => void;
+    rewrite: (entry: string) => void;
+  };
+};
+
+type AfterRenderContext = {
+  template: {
+    get: () => string;
+    set: (html: string) => void;
+    prependHead: (fragment: string) => void;
+    appendHead: (fragment: string) => void;
+    prependBody: (fragment: string) => void;
+    appendBody: (fragment: string) => void;
+  };
+};
+```
+
+Hook Context is mostly consistent with Middleware Context, so we need to pay extra attention to the additional parts of different Hooks.
+
+| UnstableMiddleware       | Hono                          | Description                           |
+| :----------------------- | :---------------------------- | :------------------------------------ |
+| `router.redirect`        | `c.redirect`                  | Refer to [Hono Context redirect](https://hono.dev/docs/api/context#redirect) documentation      |
+| `router.rewrite`         | -                             | No corresponding capability provided at the moment                                                   |
+| template API             | `c.res`                       | Refer to [Hono Context res](https://hono.dev/docs/api/context#res) documentation               |
+
+
+### Differences in Next API
+
+In Middleware and Hooks, the render function executes even without invoking `next`.
+In the new design, subsequent Middleware will only execute if the `next` function is invoked.

package/docs/en/guides/basic-features/data/data-cache.mdx

@@ -4,7 +4,7 @@ sidebar_position: 4
 ---
 # Data Caching
 
-The `cache` function allows you to cache the results of data fetching or computation.
+The `cache` function allows you to cache the results of data fetching or computation, Compared to full-page [rendering cache](/guides/basic-features/render/ssr-cache), it provides more fine-grained control over data granularity and is applicable to various scenarios such as Client-Side Rendering (CSR), Server-Side Rendering (SSR), and API services (BFF).
 
 :::info
 X.65.5 and above versions are required
@@ -12,6 +12,15 @@ X.65.5 and above versions are required
 
 ## Basic Usage
 
+:::note
+
+If you use the `cache` function in BFF, you should import the cache funtion from `@modern-js/server-runtime/cache`
+
+`import { cache } from '@modern-js/server-runtime/cache'`
+
+:::
+
+
 ```ts
 import { cache } from '@modern-js/runtime/cache';
 import { fetchUserData } from './api';
@@ -34,6 +43,8 @@ const loader = async () => {
   - `tag`: Tag to identify the cache, which can be used to invalidate the cache
   - `maxAge`: Cache validity period (milliseconds)
   - `revalidate`: Time window for revalidating the cache (milliseconds), similar to HTTP Cache-Control's stale-while-revalidate functionality
+  - `getKey`: Simplified cache key generation function based on function parameters
+  - `customKey`: Custom cache key function
 
 The type of the `options` parameter is as follows:
 
@@ -42,6 +53,12 @@ interface CacheOptions {
   tag?: string | string[];
   maxAge?: number;
   revalidate?: number;
+  getKey?: <Args extends any[]>(...args: Args) => string;
+  customKey?: <Args extends any[]>(options: {
+    params: Args;
+    fn: (...args: Args) => any;
+    generatedKey: string;
+  }) => string | symbol;
 }
 ```
 
@@ -153,6 +170,204 @@ revalidateTag('dashboard-stats'); // Invalidates the cache for both getDashboard
 ```
 
 
+#### `getKey` Parameter
+
+The `getKey` parameter simplifies cache key generation, especially useful when you only need to rely on part of the function parameters to differentiate caches. It's a function that receives the same parameters as the original function and returns a string or number as the cache key:
+
+```ts
+import { cache, CacheTime } from '@modern-js/runtime/cache';
+import { fetchUserData } from './api';
+
+const getUser = cache(
+  async (userId, options) => {
+    // Here options might contain many configurations, but we only want to cache based on userId
+    return await fetchUserData(userId, options);
+  },
+  {
+    maxAge: CacheTime.MINUTE * 5,
+    // Only use the first parameter (userId) as the cache key
+    getKey: (userId, options) => userId,
+  }
+);
+
+// The following two calls will share the cache because getKey only uses userId
+await getUser(123, { language: 'en' });
+await getUser(123, { language: 'fr' }); // Cache hit, won't request again
+
+// Different userId will use different cache
+await getUser(456, { language: 'en' }); // Won't hit cache, will request again
+```
+
+You can also use Modern.js's `generateKey` function together with getKey to generate the cache key:
+
+:::info
+
+The `generateKey` function in Modern.js ensures that a consistent and unique key is generated even if object property orders change, guaranteeing stable caching.
+
+:::
+
+```ts
+import { cache, CacheTime, generateKey } from '@modern-js/runtime/cache';
+import { fetchUserData } from './api';
+
+const getUser = cache(
+  async (userId, options) => {
+    return await fetchUserData(userId, options);
+  },
+  {
+    maxAge: CacheTime.MINUTE * 5,
+    getKey: (userId, options) => generateKey(userId),
+  }
+);
+```
+
+Additionally, `getKey` can also return a numeric type as a cache key:
+
+```ts
+const getUserById = cache(
+  fetchUserDataById,
+  {
+    maxAge: CacheTime.MINUTE * 5,
+    // Directly use the numeric ID as the cache key
+    getKey: (id) => id,
+  }
+);
+
+await getUserById(42); // Uses 42 as the cache key
+```
+
+#### `customKey` parameter
+
+The `customKey` parameter is used to customize the cache key. It is a function that receives an object with the following properties and returns a string or Symbol type as the cache key:
+
+- `params`: Array of arguments passed to the cached function
+- `fn`: Reference to the original function being cached
+- `generatedKey`: Cache key automatically generated by the framework based on input parameters
+
+:::info
+
+Generally, the cache will be invalidated in the following scenarios:
+1. The referenced cached function changes
+2. The function's input parameters change
+3. The maxAge condition is no longer satisfied
+4. The `revalidateTag` method has been called
+
+`customKey` can be used in scenarios where function references are different but shared caching is desired. If it's just for customizing the cache key, it is recommended to use `getKey`.
+
+:::
+
+This is very useful in some scenarios, such as when the function reference changes , but you want to still return the cached data.
+
+```ts
+import { cache } from '@modern-js/runtime/cache';
+import { fetchUserData } from './api';
+
+// Different function references, but share the same cache via customKey
+const getUserA = cache(
+  fetchUserData,
+  {
+    maxAge: CacheTime.MINUTE * 5,
+    customKey: ({ params }) => {
+      // Return a stable string as the cache key
+      return `user-${params[0]}`;
+    },
+  }
+);
+
+// Even if the function reference changes,
+// as long as customKey returns the same value, the cache will be hit
+const getUserB = cache(
+  (...args) => fetchUserData(...args), // New function reference
+  {
+    maxAge: CacheTime.MINUTE * 5,
+    customKey: ({ params }) => {
+      // Return the same key as getUserA
+      return `user-${params[0]}`;
+    },
+  }
+);
+
+// You can also use Symbol as a cache key (usually used to share cache within the same application)
+const USER_CACHE_KEY = Symbol('user-cache');
+const getUserC = cache(
+  fetchUserData,
+  {
+    maxAge: CacheTime.MINUTE * 5,
+    customKey: () => USER_CACHE_KEY,
+  }
+);
+
+// You can utilize the generatedKey parameter to modify the default key
+const getUserD = cache(
+  fetchUserData,
+  {
+    customKey: ({ generatedKey }) => `prefix-${generatedKey}`,
+  }
+);
+```
+
+#### `onCache` Parameter
+
+The `onCache` parameter allows you to track cache statistics such as hit rate. It's a callback function that receives information about each cache operation, including the status, key, parameters, and result.
+
+```ts
+import { cache, CacheTime } from '@modern-js/runtime/cache';
+
+// Track cache statistics
+const stats = {
+  total: 0,
+  hits: 0,
+  misses: 0,
+  stales: 0,
+  hitRate: () => stats.hits / stats.total
+};
+
+const getUser = cache(
+  fetchUserData,
+  {
+    maxAge: CacheTime.MINUTE * 5,
+    onCache({ status, key, params, result }) {
+      // status can be 'hit', 'miss', or 'stale'
+      stats.total++;
+
+      if (status === 'hit') {
+        stats.hits++;
+      } else if (status === 'miss') {
+        stats.misses++;
+      } else if (status === 'stale') {
+        stats.stales++;
+      }
+
+      console.log(`Cache ${status} for key: ${String(key)}`);
+      console.log(`Current hit rate: ${stats.hitRate() * 100}%`);
+    }
+  }
+);
+
+// Usage example
+await getUser(1); // Cache miss
+await getUser(1); // Cache hit
+await getUser(2); // Cache miss
+```
+
+The `onCache` callback receives an object with the following properties:
+
+- `status`: The cache operation status, which can be:
+  - `hit`: Cache hit, returning cached content
+  - `miss`: Cache miss, executing the function and caching the result
+  - `stale`: Cache hit but data is stale, returning cached content while revalidating in the background
+- `key`: The cache key, which is either the result of `customKey` or the default generated key
+- `params`: The parameters passed to the cached function
+- `result`: The result data (either from cache or newly computed)
+
+This callback is only invoked when the `options` parameter is provided. When using the cache function without options, the `onCache` callback is not called.
+
+The `onCache` callback is useful for:
+- Monitoring cache performance
+- Calculating hit rates
+- Logging cache operations
+- Implementing custom metrics
+
 ### Storage
 
 Currently, both client and server caches are stored in memory.

package/docs/en/guides/basic-features/data/data-fetch.mdx

@@ -149,9 +149,10 @@ Having the `loader` function run only on the server in SSR applications brings s
 - **Simplifies usage**: Guarantees consistent data-fetching methods in SSR applications, so developers don't have to distinguish between client and server code.
 - **Reduces client bundle size**: Moves logic code and dependencies from the client to the server.
 - **Improves maintainability**: Less direct influence of data logic on front-end UI and avoids issues of accidentally including server dependencies in the client bundle or vice versa.
+
 :::
 
-We recommend using the `fetch` API in `loader` functions to make requests. Modern.js provides a default polyfill for the `fetch` API, allowing it to be used on the server. This means you can fetch data in a consistent manner whether in CSR or SSR:
+We recommend using the `fetch` API in `loader` functions to make requests. Since `fetch` works similarly on the client and server, you can fetch data in a consistent manner whether in CSR or SSR:
 
 ```tsx
 export async function loader() {

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

@@ -136,13 +136,14 @@ Full-stack projects refer to projects that use Custom Web Server, SSR or BFF. Th
 :::info
 1. Currently, Modern.js does not support deployment on Netlify Edge Functions. We will support it in future versions.
 2. You can refer to the [deployment project example](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-ssr).
+
 :::
 
 
 ### Monorepo
 
 :::info
-The following guide is mainly for full-stack projects, for pure CSR projects, just follow [Pure Frontend Project](#Pure Frontend Project) to deploy.
+The following guide is mainly for full-stack projects, for pure CSR projects, just follow [Pure Frontend Project](#pure-front-end-project-1) to deploy.
 :::
 
 For Monorepo projects, in addition to building our current project, you also need to build other sub-projects in the repository that the current project depends on.
@@ -330,6 +331,7 @@ For branch deployment, follow these steps:
 :::info
 1. Running `MODERNJS_DEPLOY=ghPages modern deploy` will build the production output for GitHub in the .output directory.
 2. You can refer to the [project](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr)
+
 :::
 
 For GitHub Actions deployment, select Settings > Pages > Source > GitHub Actions, and add a workflow file to the project. You can refer to the [example](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr).

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

@@ -8,7 +8,7 @@ Modern.js provides **JSX syntax** and **HTML(EJS) syntax** to customize the HTML
 
 ## JSX Syntax
 
-According to Modern.js conventions, you can create a `Document.[jt]sx` file under `src/` or the entry directory and default export a component". The rendering result of this component can be used as the HTML template of the entry.
+According to Modern.js conventions, you can create a `Document.[jt]sx` file under `src/` or the entry directory and default export a component. The rendering result of this component can be used as the HTML template of the entry.
 
 For example, consider the following directory structure:
 
@@ -218,9 +218,9 @@ The implementation of custom HTML fragments is to merge the fragments with the b
 
 :::
 
-### Custom the entire HTML Template
+### Customize the entire HTML Template
 
-In some cases, HTML fragments may be is not better meet the customization requirements. Modern.js provides a fully customized way.
+In some cases, HTML fragments may not offer enough control. Modern.js provides a fully customized way.
 
 :::caution Note
 It is generally not recommended to directly override the default HTML template, as some functional options may be lost. If it is truly necessary to customize the entire HTML template, it is recommended to modify based on the built-in template as needed.

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

@@ -1,6 +1,6 @@
 # Server-Side Rendering
 
-Server-Side Rendering (SSR) involves rendering the HTML content of a webpage-side and then sending the fully-rendered page to the browser. The browser only needs to display the page without additional rendering.
+Server-Side Rendering (SSR) involves rendering the HTML content of a webpage server-side and then sending the fully-rendered page to the browser. The browser only needs to display the page without additional rendering.
 
 The main advantages are:
 
@@ -320,4 +320,4 @@ In this case, the `epicMiddleware` instance is created outside the component, an
 
 This code does not cause issues on the client-side. However, in SSR, the Middleware instance remains non-disposable. Each time the component renders, calling `epicMiddleware.run(rootEpic)` adds new event bindings internally, causing the entire object to grow continuously, ultimately affecting application performance.
 
-Such issues are not easily noticed in CSR. When transitioning from CSR to SSR, if you're unsure whether your application has such hidden pitfalls, consider stress testing the application.
+Such issues are not easily noticed in CSR. When transitioning from CSR to SSR, if you're unsure whether your application has such hidden pitfalls, consider stress testing the application.

package/docs/en/guides/concept/entries.mdx

@@ -76,7 +76,7 @@ By default, Modern.js scans the files under `src/` before starting the project,
 
 :::tip
 
-- You can custom the recognition directory for page entries by using [source.entriesDir](/configure/app/source/entries-dir).
+- You can customize the recognition directory for page entries by using [source.entriesDir](/configure/app/source/entries-dir).
 - If you need to customize the entry points, please refer to [Custom Entries](#custom-entries).
 
 :::

package/docs/en/guides/get-started/quick-start.mdx

@@ -148,7 +148,7 @@ info    Starting production server...
   > Network:  http://192.168.0.1:8080/
 ```
 
-Open `http://localhost:8000/` in the browser, and the content should be consistent with that of `pnpm run dev`.
+Open `http://localhost:8080/` in the browser, and the content should be consistent with that of `pnpm run dev`.
 
 ## Deployment
 

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

@@ -2,6 +2,12 @@
 
 This document details the API for Modern.js CLI plugins. CLI plugins allow you to extend and customize the functionality of Modern.js projects during the build and development process.
 
+:::info
+
+CLI plugins need to be configured via the [`plugins`](/configure/app/plugins) field in `modern.config.ts`.
+
+:::
+
 ## Plugin Basic Structure
 
 A typical CLI plugin structure is as follows:

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

@@ -2,6 +2,12 @@
 
 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
+
+Runtime plugins need to be configured via the [`plugins`](/configure/app/runtime/plugins) field in `src/modern.runtime.ts`.
+
+:::
+
 ## Plugin Structure
 
 A typical Runtime Plugin looks like this:
@@ -150,16 +156,35 @@ 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
-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>
-  );
-});
+import { RuntimePluginFuture, RuntimeReactContext } from '@modern-js/runtime';
+import { useContext, createContext } from 'react';
+
+export const ThemeContext = createContext<{ theme: string } | null>(null);
+
+export const themePlugin = (): RuntimePluginFuture => {
+  return {
+    name: 'theme-plugin',
+    setup: api => {
+      api.onBeforeRender(async context => {
+        const userPreference = await fetch('/api/user/theme-settings').then(
+          res => res.json(),
+        );
+        context.data = {
+          theme: userPreference.theme,
+        };
+      });
+
+      api.wrapRoot(App => {
+        return props => {
+          const context = useContext(RuntimeReactContext);
+          return (
+            <ThemeContext.Provider value={context.data}>
+              <App {...props} />
+            </ThemeContext.Provider>
+          );
+        };
+      });
+    },
+  };
+};
 ```

package/docs/en/tutorials/first-app/c05-loader.mdx

@@ -7,7 +7,7 @@ In the previous chapter, we learned how to add client route.
 
 In this chapter, we will learn how to add **Loader** to the routing component.
 
-By far, we have provided data to components through hardcoding. If you want to get data from the remote, you usually use `useEffect` to do it. But when SSR is enabled, `useEffect` will not be executed at the server level, so this SSR can only render a very limited UI.
+So far, we have provided data to components through hardcoding. If you want to get data from the remote, you usually use `useEffect` to do it. But when SSR is enabled, `useEffect` will not be executed at the server level, so this SSR can only render a very limited UI.
 
 Modern.js provides the ability of Data Loader to support homogeneous data acquisition in components to maximize the value of SSR.
 

package/docs/zh/configure/app/output/filename.mdx

@@ -3,6 +3,14 @@ title: filename
 configName: output.filename
 ---
 
+:::warning
+
+在 Modern.js 开发阶段，或是使用 Modern.js 服务器部署应用时，应避免使用该配置修改 html 产物文件名，会导致页面 404。
+
+通常情况下，无需修改 html 产物文件名。常见的需求是将 `main.html` 修改为 `index.html`，请使用 [source.mainEntryName](/configure/app/source/main-entry-name)。
+
+:::
+
 # output.filename
 
 - **类型：**

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

@@ -1,39 +1,18 @@
----
-sidebar_position: 9
----
-
 # plugins
 
 - **类型：** `CliPlugin[]`
 - **默认值：** `[]`
 
-用于配置自定义的 Modern.js 框架插件。
-
-自定义插件的编写方式请参考 [如何编写插件](/plugin/plugin-system)。
+用于配置自定义的 Modern.js 框架 CLI 插件。自定义 CLI 插件的编写方式请参考 [如何编写 CLI 插件](/plugin/introduction.html#cli-插件)。
 
 ## 注意事项
 
-该选项**用于配置框架插件**，如果你需要配置其他类型的插件，请选择对应的配置方式：
+该选项**用于配置框架 CLI 插件**，如果你需要配置其他类型的插件，请选择对应的配置方式：
 
 - 配置 Rsbuild 插件，请使用 [builderPlugins](/configure/app/builder-plugins) 配置项。
 - 配置 Rspack 或 webpack 插件，请使用 [tools.bundlerChain](/configure/app/tools/bundler-chain) 配置项。
 - 配置 Babel 插件，请使用 [tools.babel](/configure/app/tools/babel) 配置项。
-
-## 插件类型
-
-Modern.js 中内置了三种不同的框架插件：
-
-- `CLI 插件`，适用于本地开发、编译构建阶段，可以在命令行和编译阶段扩展各种能力。
-- `Server 插件`，适用于服务端。
-- `Runtime 插件`，适用于前端运行时。
-
-目前 Modern.js 开放了自定义 CLI 插件的能力，Server 插件和 Runtime 插件会在后续开放。
-
-## 插件执行顺序
-
-默认情况下，自定义插件会按照 `plugins` 数组的顺序依次执行，Modern.js 内置插件的执行时机早于自定义插件。
-
-当插件内部使用了控制顺序的相关字段，比如 `pre`、`post` 时，会基于声明的字段对执行顺序进行调整，详见 [插件结构](/plugin/plugin-system)。
+- 配置框架 Runtime 插件，请使用 [runtime 配置文件 plugins](/configure/app/runtime/plugins) 配置项。
 
 ## 示例