#插件介绍

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

#为什么需要插件？

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

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

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

#何时使用哪种插件？

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

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

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

• Modern.js 框架插件： 如果你的需求与 Modern.js 框架本身的功能扩展、运行时行为或服务端逻辑相关，那么你应该选择 Modern.js 插件。例如：

  • 添加自定义的命令行命令。
  • 修改应用的路由配置。
  • 定制化应用的渲染过程（如 SSR）。
  • 添加服务端中间件或处理函数。

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

#Modern.js 框架插件

#插件类型

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

#CLI 插件

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

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

// an example for 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 字段配置。

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 字段进行配置。

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 插件系统 获取更多信息。

#Rsbuild 构建插件

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

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

你可以在 modern.config.ts 中通过 builderPlugins 选项注册 Rsbuild 插件，详见 builderPlugins 构建插件。

#官方插件

#内置插件

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

#未内置的插件

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

• Image Compress 插件：将项目中用到的图片资源进行压缩处理。
• Stylus 插件：使用 Stylus 作为 CSS 预处理器。
• UMD 插件：用于构建 UMD 格式的产物。
• YAML 插件：用于引用 YAML 文件，并将其转换为 JavaScript 对象。
• TOML 插件：用于引用 TOML 文件，并将其转换为 JavaScript 对象。