• 简体中文

      • 插件介绍

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

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

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

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

      Rsbuild 构建插件

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

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

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

      Info

      可以阅读 Rsbuild 官网 - 插件 了解更多 Rsbuild 插件体系内容。

      官方插件

      内置插件

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

      插件介绍Modern.js 链接
      React 插件提供对 React 的支持-
      SVGR 插件支持将 SVG 图片转换为一个 React 组件output.disableSvgr
      output.svgDefaultExport
      Assets Retry 插件用于在静态资源加载失败时自动发起重试请求output.assetsRetry
      Type Check 插件用于在单独的进程中运行 TypeScript 类型检查output.disableTsChecker
      tools.tsChecker
      Source Build 插件用于 monorepo 场景，支持引用其他子目录的源代码，并完成构建和热更新experiments.sourceBuild
      Check Syntax 插件用于分析产物的语法兼容性，判断是否存在导致兼容性问题的高级语法security.checkSyntax
      CSS Minimizer 插件用于自定义 CSS 压缩工具，切换到 cssnano 或其他工具进行 CSS 压缩tools.minifyCss
      Rem 插件用于实现移动端页面的 rem 自适应布局output.convertToRem

      未内置的插件

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

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