> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# 插件介绍

Modern.js 提供了一套强大的插件体系，允许开发者通过编写插件来扩展框架功能、定制构建流程，以及满足各种个性化的开发需求。无论你是想添加一个自定义命令、优化构建产物，还是实现一套独特的部署方案，Modern.js 的插件系统都能为你提供强大的支持。

## 为什么需要插件？

在 Web 应用开发中，我们经常会遇到一些框架本身无法直接满足的需求，例如：

- **我想添加一个自定义的命令行工具，来帮助我自动化一些任务。**
- **我希望能够处理一种新的文件格式，比如 `.xyz`。**
- **我需要在应用启动前执行一些初始化的操作。**
- **我想对构建生成的 CSS 文件进行特殊的处理。**
- **我需要定制应用的路由逻辑，或者添加一些服务端中间件。**

在没有插件系统的情况下，这些需求可能需要修改框架源码，或者采用一些繁琐的 hack 手段。而 Modern.js 的插件系统提供了一种优雅、灵活且可维护的解决方案。

## 何时使用哪种插件？

Modern.js 提供了两种主要的插件类型：Modern.js 框架插件和 Rsbuild 构建插件。选择哪种插件取决于你的具体需求：

- **Rsbuild 构建插件：** 如果你的需求与构建过程密切相关，特别是涉及到 Rspack 配置的修改，那么你应该选择 Rsbuild 插件。例如：

  - 修改 Rspack 的 `loader` 或 `plugin` 配置。
  - 处理新的文件类型。
  - 修改或编译文件内容。
  - 对构建产物进行优化或处理。

- **Modern.js 框架插件：** 如果你的需求与 Modern.js 框架本身的功能扩展、运行时行为或服务端逻辑相关，那么你应该选择 Modern.js 插件。例如：
  - 添加自定义的命令行命令。
  - 修改运行时信息。
  - 定制化应用的渲染过程（如 SSR）。
  - 添加服务端中间件或处理函数。

简单来说，需要修改 Rspack 配置时，使用 Rsbuild 插件；其他与框架相关的功能扩展，使用 Modern.js 插件。

## Modern.js 框架插件

### 插件类型

Modern.js 框架插件可以细分为三类，分别是：

#### CLI 插件

CLI 插件用于在应用执行 `modern` 命令时提供额外功能，例如添加命令、修改配置、监听文件等。大部分构建相关能力均可通过 CLI 插件实现。

CLI 插件可通过 `modern.config.ts` 中的 `plugins` 字段进行配置。

```ts title="modern.config.ts"
// bff 的示例
import { appTools, defineConfig } from '@modern-js/app-tools';
import { bffPlugin } from '@modern-js/plugin-bff';

export default defineConfig({
  plugins: [appTools(), bffPlugin()],
});
```

#### Runtime 插件

Runtime 插件用于在应用运行 React 代码时提供额外功能，例如执行初始化行为、实现 React 高阶组件（HOC）封装。

Runtime 插件通过 `src/modern.runtime.ts` 中的 `plugins` 字段配置。

```ts title="src/modern.runtime.ts"
import { defineRuntimeConfig } from '@modern-js/runtime';
import { routerPlugin } from '@modern-js/runtime/router';

export default defineRuntimeConfig({
  plugins: [routerPlugin()],
});
```

#### Server 插件

Server 插件用于在应用接受请求时提供额外功能，例如添加中间件、修改请求响应等。

Server 插件通过 `server/modern.server.ts` 中的 `plugins` 字段进行配置。

```ts title="server/modern.server.ts"
import { defineServerConfig } from '@modern-js/server-runtime';

export default defineServerConfig({
  plugins: [
    {
      name: 'custom-plugin-in-config',
      setup: api => {
        api.onPrepare(() => {
          const { middlewares } = api.getServerContext();

          middlewares?.push({
            name: 'server-plugin-middleware',
            handler: async (c, next) => {
              c.res.headers.set('x-render-middleware-plugin', 'ok');
              await next();
            },
          });
        });
      },
    },
  ],
});
```

### 开发插件

如果你需要开发 Modern.js 框架插件，请阅读 [Modern.js 插件系统](/zh/plugin/plugin-system.md) 获取更多信息。

## Rsbuild 构建插件

Rsbuild 是 Modern.js 底层的构建工具，通过添加 Rsbuild 插件可修改默认的构建行为，添加各类额外功能，包括但不限于：

- 修改 Rsbuild 配置
- 处理新的文件类型
- 修改或编译文件
- 部署产物

你可以在 `modern.config.ts` 中通过 `builderPlugins` 选项注册 Rsbuild 插件，详见 [builderPlugins 构建插件](/zh/configure/app/builder-plugins.md)。

:::info
可以阅读 [Rsbuild 官网 - 插件](https://v2.rsbuild.rs/plugins/list/index) 了解更多 Rsbuild 插件体系内容。
:::

### 官方插件

#### 内置插件

以下为已在 Modern.js 中内置的 Rsbuild 官方插件，无需安装，即可启用：

| 插件                                                                           | 介绍                                                               | Modern.js 链接                                                                                                                            |
| ---------------------------------------------------------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| [React 插件](https://v2.rsbuild.rs/zh/plugins/list/plugin-react)               | 提供对 React 的支持                                                    | -                                                                                                                                       |
| [SVGR 插件](https://v2.rsbuild.rs/zh/plugins/list/plugin-svgr)                 | 支持将 SVG 图片转换为一个 React 组件                                         | [tools.svgr](/zh/configure/app/tools/svgr.md)                                                                                           |
| [Assets Retry 插件](https://github.com/rstackjs/rsbuild-plugin-assets-retry)   | 用于在静态资源加载失败时自动发起重试请求                                             | [output.assetsRetry](/zh/configure/app/output/assets-retry.md)                                                                          |
| [Type Check 插件](https://github.com/rstackjs/rsbuild-plugin-type-check)       | 用于在单独的进程中运行 TypeScript 类型检查                                      | [output.disableTsChecker](/zh/configure/app/output/disable-ts-checker.md)<br />[tools.tsChecker](/zh/configure/app/tools/ts-checker.md) |
| [Source Build 插件](https://github.com/rstackjs/rsbuild-plugin-source-build)   | 用于 monorepo 场景，支持引用其他子目录的源代码，并完成构建和热更新                           | [experiments.sourceBuild](/zh/configure/app/experiments/source-build.md)                                                                |
| [Check Syntax 插件](https://github.com/rstackjs/rsbuild-plugin-check-syntax)   | 用于分析产物的语法兼容性，判断是否存在导致兼容性问题的高级语法                                  | [security.checkSyntax](/zh/configure/app/security/check-syntax.md)                                                                      |
| [CSS Minimizer 插件](https://github.com/rstackjs/rsbuild-plugin-css-minimizer) | 用于自定义 CSS 压缩工具，切换到 [cssnano](https://cssnano.co/) 或其他工具进行 CSS 压缩 | [tools.minifyCss](/zh/configure/app/tools/minify-css.md)                                                                                |
| [Rem 插件](https://github.com/rstackjs/rsbuild-plugin-rem)                     | 用于实现移动端页面的 rem 自适应布局                                             | [output.convertToRem](/zh/configure/app/output/convert-to-rem.md)                                                                       |

#### 未内置的插件

以下是未在 Modern.js 中内置的 Rsbuild 官方插件：

- [Image Compress 插件](https://github.com/rstackjs/rsbuild-plugin-image-compress)：将项目中用到的图片资源进行压缩处理。
- [Stylus 插件](https://v2.rsbuild.rs/zh/plugins/list/plugin-stylus)：使用 Stylus 作为 CSS 预处理器。
- [UMD 插件](https://github.com/rstackjs/rsbuild-plugin-umd)：用于构建 UMD 格式的产物。
- [YAML 插件](https://github.com/rstackjs/rsbuild-plugin-yaml)：用于引用 YAML 文件，并将其转换为 JavaScript 对象。
- [TOML 插件](https://github.com/rstackjs/rsbuild-plugin-toml)：用于引用 TOML 文件，并将其转换为 JavaScript 对象。


```
```