#Introduction

Modern.js provides a powerful plugin system that allows developers to extend the framework's functionality, customize the build process, and meet a variety of personalized development needs. Whether you want to add a custom command, optimize build output, or implement a unique deployment solution, Modern.js's plugin system provides robust support.

#Why Plugins?

In web application development, we often encounter needs that the framework itself cannot directly satisfy, such as:

• I want to add a custom command-line tool to help me automate some tasks.
• I want to be able to handle a new file format, such as .xyz.
• I need to perform some initialization operations before the application starts.
• I want to perform special processing on the generated CSS files.
• I need to customize the application's routing logic or add some server-side middleware.

Without a plugin system, these requirements might require modifying the framework's source code or resorting to cumbersome hacks. Modern.js's plugin system offers an elegant, flexible, and maintainable solution.

#When to Use Which Plugin?

Modern.js offers two main types of plugins: Modern.js framework plugins and Rsbuild build plugins. The choice of which plugin to use depends on your specific needs:

• Rsbuild Build Plugins: If your needs are closely related to the build process, especially involving modifications to Rspack configuration, then you should choose an Rsbuild plugin. For example:

  • Modifying Rspack loader or plugin configurations.
  • Handling new file types.
  • Modifying or compiling file contents.
  • Optimizing or processing build artifacts.

• Modern.js Framework Plugins: If your needs relate to the extension of Modern.js framework itself, runtime behavior, or server-side logic, then you should choose a Modern.js plugin. For example:

  • Adding custom command-line commands.
  • Modifying the application's routing configuration.
  • Customizing the application's rendering process (e.g., SSR).
  • Adding server-side middleware or handler functions.

In short, use Rsbuild plugins when you need to modify Rspack configurations; use Modern.js plugins for other framework-related extensions.

#Modern.js Framework Plugins

#Plugin Types

Modern.js framework plugins can be further divided into three categories:

#CLI Plugins

CLI plugins are used to provide additional functionality when running modern commands in the application, such as adding commands, modifying configurations, and listening for file changes. Most build-related capabilities can be implemented through CLI plugins.

CLI plugins can be configured via the plugins field in modern.config.ts.

// 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 Plugins

Runtime plugins are used to provide additional functionality when the application is running React code, such as performing initialization behaviors and implementing React Higher-Order Component (HOC) encapsulation.

Runtime plugins are configured via the plugins field in src/modern.runtime.ts.

import { defineRuntimeConfig } from '@modern-js/runtime';
import { routerPlugin } from '@modern-js/runtime/router';

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

#Server Plugins

Server plugins are used to provide additional functionality when the application receives requests, such as adding middleware and modifying request responses.

Server plugins are configured via the plugins field in 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();
            },
          });
        });
      },
    },
  ],
});

#Developing Plugins

If you need to develop Modern.js framework plugins, please read Modern.js Plugin System for more information.

#Rsbuild Build Plugins

Rsbuild is the underlying build tool for Modern.js. By adding Rsbuild plugins, you can modify the default build behavior and add various additional functionalities, including but not limited to:

• Modifying Rsbuild configuration
• Handling new file types
• Modifying or compiling files
• Deploying artifacts

You can register Rsbuild plugins in modern.config.ts via the builderPlugins option. See builderPlugins for details.

#Official Plugins

#Built-in Plugins

The following are official Rsbuild plugins that are already built into Modern.js. They can be enabled without installation:

#Plugins Not Built-in

The following are official Rsbuild plugins that are not built into Modern.js:

• Image Compress Plugin: Compresses image resources used in the project.
• Stylus Plugin: Uses Stylus as the CSS preprocessor.
• UMD Plugin: Used to build UMD format artifacts.
• YAML Plugin: Used to reference YAML files and convert them to JavaScript objects.
• TOML Plugin: Used to reference TOML files and convert them to JavaScript objects.