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 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 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:
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 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()], // <- 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 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
unpluginpackage is >= v1.6.0.