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

# 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`.

```ts title="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`.

```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 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`.

```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();
            },
          });
        });
      },
    },
  ],
});
```

### Developing Plugins

If you need to develop Modern.js framework plugins, please read [Modern.js Plugin System](/plugin/plugin-system.md) 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](/configure/app/builder-plugins.md) for details.

:::info
You can read [Rsbuild Official Website - Plugins](https://v2.rsbuild.rs/plugins/list/index) 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:

| Plugin                                                                           | Description                                                                                                                                     | Modern.js Link                                                                                                                          |
| -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| [React Plugin](https://v2.rsbuild.rs/plugins/list/plugin-react)                  | Provides support for React                                                                                                                      | -                                                                                                                                       |
| [SVGR Plugin](https://v2.rsbuild.rs/plugins/list/plugin-svgr)                    | Supports converting SVG images into React components                                                                                            | [output.disableSvgr](/configure/app/output/disable-svgr.md)<br />[output.svgDefaultExport](/configure/app/output/svg-default-export.md) |
| [Assets Retry Plugin](https://github.com/rstackjs/rsbuild-plugin-assets-retry)   | Automatically retries requests when static asset loading fails                                                                                  | [output.assetsRetry](/configure/app/output/assets-retry.md)                                                                             |
| [Type Check Plugin](https://github.com/rstackjs/rsbuild-plugin-type-check)       | Runs TypeScript type checking in a separate process                                                                                             | [output.disableTsChecker](/configure/app/output/disable-ts-checker.md)<br />[tools.tsChecker](/configure/app/tools/ts-checker.md)       |
| [Source Build Plugin](https://github.com/rstackjs/rsbuild-plugin-source-build)   | For monorepo scenarios, supports referencing source code from other subdirectories and completing builds and hot updates                        | [experiments.sourceBuild](/configure/app/experiments/source-build.md)                                                                   |
| [Check Syntax Plugin](https://github.com/rstackjs/rsbuild-plugin-check-syntax)   | Analyzes the syntax compatibility of the build artifacts to determine if there are any advanced syntax features that cause compatibility issues | [security.checkSyntax](/configure/app/security/check-syntax.md)                                                                         |
| [CSS Minimizer Plugin](https://github.com/rstackjs/rsbuild-plugin-css-minimizer) | Used to customize the CSS compression tool, switch to [cssnano](https://cssnano.co/) or other tools for CSS compression                         | [tools.minifyCss](/configure/app/tools/minify-css.md)                                                                                   |
| [Rem Plugin](https://github.com/rstackjs/rsbuild-plugin-rem)                     | Implements rem adaptive layout for mobile pages                                                                                                 | [output.convertToRem](/configure/app/output/convert-to-rem.md)                                                                          |

#### Plugins Not Built-in

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

- [Image Compress Plugin](https://github.com/rstackjs/rsbuild-plugin-image-compress): Compresses image resources used in the project.
- [Stylus Plugin](https://v2.rsbuild.rs/plugins/list/plugin-stylus): Uses Stylus as the CSS preprocessor.
- [UMD Plugin](https://github.com/rstackjs/rsbuild-plugin-umd): Used to build UMD format artifacts.
- [YAML Plugin](https://github.com/rstackjs/rsbuild-plugin-yaml): Used to reference YAML files and convert them to JavaScript objects.
- [TOML Plugin](https://github.com/rstackjs/rsbuild-plugin-toml): Used to reference TOML files and convert them to JavaScript objects.


```
```