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 Webpack or Rspack configuration, then you should choose an Rsbuild plugin. For example:

    • Modifying Webpack/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 Webpack/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.

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.

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

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

Modern.js officially uses the new plugin mechanism starting from 2.66.0.

If your current version is lower than 2.66.0, you can upgrade by running npx modern upgrade.

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.

TIP

Starting from 2.46.0, Modern.js upgraded its underlying build tool to Rsbuild.

If your current version is lower than 2.46.0, you can upgrade by running npx modern upgrade.

INFO

You can read Rsbuild Official Website - Plugins to learn more about the Rsbuild plugin system.

Official Plugins

Built-in Plugins

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

PluginDescriptionModern.js Link
React PluginProvides support for React-
SVGR PluginSupports converting SVG images into React componentsoutput.disableSvgr
output.svgDefaultExport
Styled Components PluginProvides compile-time support for styled-componentstools.styledComponents
Assets Retry PluginAutomatically retries requests when static asset loading failsoutput.assetsRetry
Type Check PluginRuns TypeScript type checking in a separate processoutput.disableTsChecker
tools.tsChecker
Node Polyfill PluginInjects polyfills for Node core modules in the browseroutput.disableNodePolyfill
Source Build PluginFor monorepo scenarios, supports referencing source code from other subdirectories and completing builds and hot updatesexperiments.sourceBuild
Check Syntax PluginAnalyzes the syntax compatibility of the build artifacts to determine if there are any advanced syntax features that cause compatibility issuessecurity.checkSyntax
CSS Minimizer PluginUsed to customize the CSS compression tool, switch to cssnano or other tools for CSS compressiontools.minifyCss
Pug PluginProvides support for the Pug template enginetools.pug
Rem PluginImplements rem adaptive layout for mobile pagesoutput.convertToRem
YAML PluginUsed to reference YAML files and convert them to JavaScript objectsYAML Files
TOML PluginUsed to reference TOML files and convert them to JavaScript objectsTOML Files

Plugins Not Built-in

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