Rsbuild provides a lightweight yet powerful plugin system to implement most of its functionality and allows for user extension.
Plugins written by developers can modify the default behavior of Rsbuild and add various additional features, including but not limited to:
Before developing a Rsbuild plugin, you may have been familiar with the plugin systems of tools such as Webpack, Vite, esbuild, etc.
Generally, Rsbuild's plugin API is similar to esbuild, and compared with Webpack / Rspack plugins, Rsbuild's plugin API is more simple and easier to get started with.
From a functional perspective, Rsbuild's plugin API mainly revolves around Rsbuild's operation process and build configuration and provides some hooks for extension. On the other hand, Rspack's plugin API is more complex and rich, capable of modifying every aspect of the bundling process.
Rspack plugins can be integrated into Rsbuild plugins. If the hooks provided by Rsbuild do not meet your requirements, you can also implement the functionality using Rspack plugin and register Rspack plugins in the Rsbuild plugin:
Plugins provide a function similar to (options?: PluginOptions) => RsbuildPlugin
as an entry point.
Registering the plugin:
Function-based plugins can accept an options object and return a plugin instance, managing internal state through closures.
The roles of each part are as follows:
name
property is used to label the plugin's name.setup
serves as the main entry point for the plugin logic.api
object contains various hooks and utility functions.The naming convention for plugins is as follows:
pluginAbc
and exported by name.name
of the plugin follows the format scope:foo-bar
or plugin-foo-bar
, adding scope:
can avoid naming conflicts with other plugins.Here is an example:
The name
of official Rsbuild plugins uniformly uses rsbuild:
as a prefix, for example, rsbuild:react
corresponds to @rsbuild/plugin-react
.
rsbuild-plugin-template is a minimal Rsbuild plugin template repository that you can use as a basis for developing your Rsbuild plugin.
Rsbuild supports building outputs for multiple environments at the same time, and supports add plugins for specified environment.
If you want the plugin you develop to support use as an Environment plugin, you need to pay attention to the following points:
getRsbuildConfig
to get environment information.Here is an example:
Rsbuild uses lifetime planning work internally, and plugins can also register hooks to take part in any stage of the workflow and implement their own features.
The full list of Rsbuild's lifetime hooks can be found in the API References.
The Rsbuild does not take over the hooks of the underlying Rspack, whose documents can be found here: Rspack Plugin API.
Custom plugins can usually get config from function parameters, just define and use it at your pleasure.
But sometimes you may need to read and change the public config of the Rsbuild. To begin with, you should understand how the Rsbuild generates and uses its config:
api.modifyRsbuildConfig(...)
.Refer to this tiny example:
There are 3 ways to use Rsbuild config:
api.modifyRsbuildConfig(config => {})
to modify config.api.getRsbuildConfig()
to get Rsbuild config.api.getNormalizedConfig()
to get finally normalized config.When normalized, it will again merge the config object with the default values and make sure the optional properties exist. So for PluginUploadDist, part of its type looks like:
The return value type of getNormalizedConfig()
is slightly different from that of RsbuildConfig
and is narrowed compared to the types described elsewhere in the documentation.
You don't need to fill in the defaults when you use it.
Therefore, the best way to use configuration options is to
api.modifyRsbuildConfig(config => {})
api.getNormalizedConfig()
as the actual config used by the plugin in the further lifetime.Rsbuild plugin allows you to modify the built-in Rspack configuration, including:
For example, register eslint-rspack-plugin via Rsbuild plugin: