plugins#

Used to register Rsbuild plugins.

Async plugin (promise) in the plugins array will be resolved, and falsy values will be ignored.

• Type:

type Falsy = false | null | undefined;

type RsbuildPlugins = (
  | RsbuildPlugin
  | Falsy
  | Promise<RsbuildPlugin | Falsy | RsbuildPlugins>
  | RsbuildPlugins
)[];

• Default: undefined

Please check out the Plugin List page to discover all available plugins.

Example#

For example, register the Stylus plugin in Rsbuild.

• Installing the plugin:

npm add @rsbuild/plugin-stylus -D

• Registering the plugin:

import { defineConfig } from '@rsbuild/core';
import { pluginStylus } from '@rsbuild/plugin-stylus';

export default defineConfig({
  plugins: [pluginStylus()],
});

Execution Order#

By default, plugins are executed in the order they appear in the plugins array. Built-in Rsbuild plugins are executed before user-registered plugins.

When a plugin internally uses fields that control the order, such as pre and post, the execution order is adjusted based on them. See Pre Plugins for more details.

Nested Plugins#

Rsbuild also supports adding nested plugins. You can pass in an array containing multiple plugins, similar to a plugin preset collection. This is particularly useful for implementing complex functionalities that require a combination of multiple plugins (such as framework integration).

function myPlugin() {
  return [fooPlugin(), barPlugin()];
}

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

Local Plugins#

If your local code repository contains Rsbuild plugins, you can import them using relative paths.

import { defineConfig } from '@rsbuild/core';
import { pluginCustom } from './plugins/pluginCustom';

export default defineConfig({
  plugins: [pluginCustom()],
});

Plugin Options#

If a plugin provides custom options, you can pass the configurations through the plugin function's parameters.

import { defineConfig } from '@rsbuild/core';
import { pluginStylus } from '@rsbuild/plugin-stylus';

export default defineConfig({
  plugins: [
    pluginStylus({
      stylusOptions: {
        lineNumbers: false,
      },
    }),
  ],
});

Plugin registration phase#

It should be noted that plugin registration can only be performed during the Rsbuild initialization phase. You cannot dynamically add other plugins within a plugin through the plugin API:

// Wrong
function myPlugin() {
  return {
    setup: (api) => {
      api.modifyRsbuildConfig((config, { mergeRsbuildConfig }) => {
        return mergeRsbuildConfig(config, {
          plugins: [fooPlugin(), barPlugin()], // <- it won't work
        });
      });
    },
  };
}

// Correct
function myPlugin() {
  return [fooPlugin(), barPlugin()];
}

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

Rspack Plugins#

The plugins option is used to register Rsbuild plugins. If you need to register Rspack or Webpack plugins, please use tools.rspack.

export default {
  // Rsbuild Plugins
  plugins: [pluginStylus()],
  tools: {
    rspack: {
      // Rspack or Webpack Plugins
      plugins: [new SomeWebpackPlugin()],
    },
  },
};

Unplugin#

unplugin is a unified plugin system for various build tools. You can use plugins implemented based on unplugin in Rsbuild, just import the /rspack subpath of the plugin and register it via tools.rspack.

Here is an example of using unplugin-vue-components:

import { defineConfig } from '@rsbuild/core';
import { pluginVue } from '@rsbuild/plugin-vue';
import Components from 'unplugin-vue-components/rspack';

export default defineConfig({
  plugins: [pluginVue()],
  tools: {
    rspack: {
      plugins: [
        Components({
          // options
        }),
      ],
    },
  },
});

Please ensure that the version of unplugin package is >= v1.6.0.