English

plugins

Used to register Rsbuild plugins.

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 Sass plugin in Rsbuild.

Installing the plugin:

npm

yarn

pnpm

bun

npm add @rsbuild/plugin-sass -D

Registering the plugin:

rsbuild.config.ts

import { defineConfig } from '@rsbuild/core';
import { pluginSass } from '@rsbuild/plugin-sass';

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

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.

Conditional registration

The falsy value in the plugins array will be ignored, which allows you to conveniently register plugins based on some judgment conditions:

rsbuild.config.ts

const isProd = process.env.NODE_ENV === 'production';

export default defineConfig({
  plugins: [isProd && somePlugin()],
});

Async plugins

If the plugin is async, you can return a Promise object or use an async function, and Rsbuild will automatically wait for the Promise to be resolved:

rsbuild.config.ts

async function myPlugin() {
  await someAsyncOperation();
  return {
    name: 'my-plugin',
    setup(api) {
      // ...
    },
  };
}

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

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

rsbuild.config.ts

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.

rsbuild.config.ts

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.

rsbuild.config.ts

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:

rsbuild.config.ts

// Wrong
function myPlugin() {
  return {
    setup(api) {
      api.modifyRsbuildConfig((config, { mergeRsbuildConfig }) => {
        return mergeRsbuildConfig(config, {
          plugins: [fooPlugin(), barPlugin()], // <- this will not 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.

rsbuild.config.ts

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:

rsbuild.config.ts

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

TIP

When using the transform hook in unplugin, please use the transformInclude hook to match the specified module. When the transform hook matches the .html module, it will replace the default EJS transformation of the html-rspack-plugin.

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

plugins

Used to register Rsbuild plugins.

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 Sass plugin in Rsbuild.

Installing the plugin:

npm

yarn

pnpm

bun

npm add @rsbuild/plugin-sass -D

Registering the plugin:

rsbuild.config.ts

import { defineConfig } from '@rsbuild/core';
import { pluginSass } from '@rsbuild/plugin-sass';

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

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.

Conditional registration

The falsy value in the plugins array will be ignored, which allows you to conveniently register plugins based on some judgment conditions:

rsbuild.config.ts

const isProd = process.env.NODE_ENV === 'production';

export default defineConfig({
  plugins: [isProd && somePlugin()],
});

Async plugins

If the plugin is async, you can return a Promise object or use an async function, and Rsbuild will automatically wait for the Promise to be resolved:

rsbuild.config.ts

async function myPlugin() {
  await someAsyncOperation();
  return {
    name: 'my-plugin',
    setup(api) {
      // ...
    },
  };
}

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

Nested plugins

rsbuild.config.ts

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.

rsbuild.config.ts

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.

rsbuild.config.ts

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:

rsbuild.config.ts

// Wrong
function myPlugin() {
  return {
    setup(api) {
      api.modifyRsbuildConfig((config, { mergeRsbuildConfig }) => {
        return mergeRsbuildConfig(config, {
          plugins: [fooPlugin(), barPlugin()], // <- this will not 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.

rsbuild.config.ts

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

Unplugin

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

rsbuild.config.ts

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

TIP

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

#plugins

#Example

#Execution order

#Conditional registration

#Async plugins

#Nested plugins

#Local plugins

#Plugin options

#Plugin registration phase

#Rspack plugins

#Unplugin

#plugins

#Example

#Execution order

#Conditional registration

#Async plugins

#Nested plugins

#Local plugins

#Plugin options

#Plugin registration phase

#Rspack plugins

#Unplugin

plugins

Example

Execution order

Conditional registration

Async plugins

Nested plugins

Local plugins

Plugin options

Plugin registration phase

Rspack plugins

Unplugin

plugins

Example

Execution order

Conditional registration

Async plugins

Nested plugins

Local plugins

Plugin options

Plugin registration phase

Rspack plugins

Unplugin