plugins
Registers 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, to register the Sass plugin in Rsbuild:
- Installing the plugin:
npm add @rsbuild/plugin-sass -D- Registering the plugin:
import { defineConfig } from '@rsbuild/core';
import { pluginSass } from '@rsbuild/plugin-sass';
export default defineConfig({
plugins: [pluginSass()],
});Execution order
By default, plugins run in the order they appear in the plugins array, and built-in Rsbuild plugins run before user-registered plugins.
If a plugin defines ordering fields such as pre or post, Rsbuild adjusts the execution order accordingly. See Pre Plugins for more details.
Conditional registration
Falsy values in the plugins array are ignored, which lets you register plugins conditionally:
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:
async function myPlugin() {
await someAsyncOperation();
return {
name: 'my-plugin',
setup(api) {
// ...
},
};
}
export default {
plugins: [myPlugin()],
};Nested plugins
Rsbuild also supports nested plugins. You can pass an array that contains multiple plugins, similar to a plugin preset. This is useful for complex features that combine several plugins, such as framework integrations.
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
Plugin registration only runs 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()], // <- 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.
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
}),
],
},
},
});
When you use the transform hook in unplugin, also use the transformInclude hook to target specific modules. If the transform hook matches an .html module, it replaces the default EJS transform from the html-rspack-plugin.
Please ensure that the version of
unpluginpackage is >= v1.6.0.