This section describes the core plugin types and APIs.
The type of the plugin object. The plugin object contains the following properties:
name
: The name of the plugin, a unique identifier.setup
: The setup function of the plugin, which can be an async function. This function is called once when the plugin is initialized. The plugin API provides the context info, utility functions and lifecycle hooks. For a complete introduction to lifecycle hooks, please read the Plugin Hooks chapter.pre
: Declare the names of pre-plugins, which will be executed before the current plugin.post
: Declare the names of post-plugins, which will be executed after the current plugin.remove
: Declare the plugins that need to be removed, you can pass an array of plugin names.The type of the plugin object, which contains the following properties:
You can import this type from @rsbuild/core
:
By default, plugins are executed in the order they are added. You can declare pre-execution plugins using the pre
field.
For example, consider the following two plugins:
The Bar plugin is configured with the Foo plugin in its pre
field, so the Foo plugin will always be executed before the Bar plugin.
Similarly, you can declare post-execution plugins using the post
field.
The Bar plugin is configured with the Foo plugin in its post
field, so the Foo plugin will always be executed after the Bar plugin.
You can remove other plugins within a plugin using the remove
field.
For example, if you register both the Foo and Bar plugins mentioned above, the Foo plugin will not take effect because the Bar plugin declares the removal of the Foo plugin.
It should be noted that if the current plugin is registered as a specific environment plugin, only the removal of plugins in the same environment is supported, and global plugins cannot be removed.
api.context
is a read-only object that provides some context information.
The content of api.context
is exactly the same as rsbuild.context
, please refer to rsbuild.context.
Get the Rsbuild config, this method must be called after the modifyRsbuildConfig
hook is executed.
You can specify the type of Rsbuild config to read by using the type
parameter:
Get the all normalized Rsbuild config or the Rsbuild config of a specified environment, this method must be called after the modifyRsbuildConfig hook is executed.
Compared with the api.getRsbuildConfig
method, the config returned by this method has been normalized, and the type definition of the config will be narrowed. For example, the undefined
type of config.html
will be removed.
It is recommended to use this method to get the Rsbuild config.
Determines whether a plugin has been registered.
Used to transform the code of modules.
api.transform
accepts two params:
descriptor
: an object describing the module's matching conditions.handler
: a transformation function that takes the current module code and returns the transformed code.For example, match modules with the .pug
extension and transform them to JavaScript code:
The descriptor param is an object describing the module's matching conditions.
The descriptor
param supports the following matching conditions:
test
: matches module's path (without query), the same as Rspack's Rule.test.targets
: matches the Rsbuild output.target, and applies the current transform function only to the matched targets.environments
: matches the Rsbuild environment name, and applies the current transform function only to the matched environments.resourceQuery
: matches module's query, the same as Rspack's Rule.resourceQuery.raw
: if raw is true
, the transform handler will receive the Buffer type code instead of the string type.layer
: the same as Rspack's Rule.layer.issuerLayer
: the same as Rspack's Rule.issuerLayer.The handler param is a transformation function that takes the current module code and returns the transformed code.
The handler
function provides the following params:
code
: The code of the module.resource
: The absolute path of the module, including the query.resourcePath
: The absolute path of the module, without the query.resourceQuery
: The query of the module.environment
: The environment context for current build.addDependency
: Add an additional file as the dependency. The file will be watched and changes to the file will trigger rebuild.emitFile
: Emits a file to the build output.For example:
api.transform
can be thought of as a lightweight implementation of Rspack loader. It provides a simple and easy to use API and automatically calls Rspack loader at the backend to transform the code.
In Rsbuild plugins, you can quickly implement code transformation functions using api.transform
, which can handle the majority of common scenarios without having to learn how to write an Rspack loader.
Note that for some complex code transformation scenarios, api.transform
may not be sufficient. In such situations, you can implement it using the Rspack loader.
Intercept and modify module request information before module resolution begins. The same as Rspack's normalModuleFactory.hooks.resolve hook.
>= 1.0.17
a.js
file:handler
ParamThe handler
parameter is a callback function that receives a module require information and allows you to modify it.
The handler
function provides the following parameters:
resolveData
: Module request information. For details, please refer to Rspack - resolve hook.compiler
: The Compiler object of Rspack.compilation
: The Compilation object of Rspack.environment
: The environment context of the current build.Modify assets before emitting, the same as Rspack's compilation.hooks.processAssets hook.
>= 1.0.0
api.processAssets
accepts two params:
descriptor
: an object to describes the stage and matching conditions that trigger processAssets
.handler
: A callback function that receives the assets object and allows you to modify it.additional
stage:The descriptor parameter is an object to describes the stage and matching conditions that trigger processAssets
.
The descriptor
param supports the following properties:
stage
: Rspack internally divides processAssets
into multiple stages (refer to process assets stages). You can choose the appropriate stage based on the operations you need to perform.targets
: Matches the Rsbuild output.target, and applies the current processAssets function only to the matched targets.environments
: matches the Rsbuild environment name, and applies the current processAssets function only to the matched environments.The handler
parameter is a callback function that receives an assets object and allows you to modify it.
The handler
function provides the following parameters:
assets
: An object where key is the asset's pathname, and the value is data of the asset represented by the Source.compiler
: The Compiler object of Rspack.compilation
: The Compilation object of Rspack.environment
: The environment context of the current build.sources
: The Rspack Sources object, which contains multiple classes which represent a Source.Here's the list of supported stages. Rspack will execute these stages sequentially from top to bottom. Please select the appropriate stage based on the operation you need to perform.
additional
— add additional assets to the compilation.pre-process
— basic preprocessing of the assets.derived
— derive new assets from the existing assets.additions
— add additional sections to the existing assets e.g. banner or initialization code.optimize
— optimize existing assets in a general way.optimize-count
— optimize the count of existing assets, e.g. by merging them.optimize-compatibility
— optimize the compatibility of existing assets, e.g. add polyfills or vendor prefixes.optimize-size
— optimize the size of existing assets, e.g. by minimizing or omitting whitespace.dev-tooling
— add development tooling to the assets, e.g. by extracting a source map.optimize-inline
— optimize the numbers of existing assets by inlining assets into other assets.summarize
— summarize the list of existing assets.optimize-hash
— optimize the hashes of the assets, e.g. by generating real hashes of the asset content.optimize-transfer
— optimize the transfer of existing assets, e.g. by preparing a compressed (gzip) file as separate asset.analyse
— analyze the existing assets.report
— creating assets for the reporting purposes.Used for plugin communication.
api.expose
can explicitly expose some properties or methods of the current plugin, and other plugins can get these APIs through api.useExposed
.
Used for plugin communication.
api.useExposed
can get the properties or methods exposed by other plugins.
You can use Symbol as a unique identifier to avoid potential naming conflicts:
You can declare types through the generics of the function:
When communicating between plugins, you need to be aware of the order in which the plugins are executed.
For example, in the above example, if pluginParent
is not registered, or registers after pluginChild
, then api.useExposed('plugin-parent')
will return an undefined
.
You can use the pre
, post
options of the plugin object, and the order
option of the plugin hook to ensure the order is correct.