Rsbuild Instance
This section describes all the properties and methods on the Rsbuild instance object.
rsbuild.context
rsbuild.context is a read-only object that provides some context infos.
context.version
The version of @rsbuild/core currently in use.
context.entry
The entry object from the source.entry option.
type RsbuildEntry = Record<string, string | string[] | EntryDescription>;
If source.entry is set as a function, and different entry objects are returned for different targets, then context.entry will only contain the entry object corresponding to the web target.
context.targets
Build artifact type, corresponding to the output.targets option in the Rsbuild configuration.
type RsbuildTarget = 'web' | 'node' | 'web-worker' | 'service-worker';
type Context = {
targets: RsbuildTarget[];
};
context.rootPath
The root path of current build, corresponding to the cwd option of createRsbuild method.
context.distPath
The absolute path of the output directory, corresponding to the output.distPath.root config in RsbuildConfig.
context.cachePath
The absolute path of the build cache files.
context.tsconfigPath
The absolute path of the tsconfig.json file, or undefined if the tsconfig.json file does not exist in current project.
type TsconfigPath = string | undefined;
context.devServer
Dev Server information, including the current Dev Server hostname and port number.
type DevServer = {
hostname: string;
port: number;
};
context.bundlerType
The bundler type of current build.
type bundlerType = 'rspack' | 'webpack';
Rsbuild internally supports switching to webpack for comparative testing, so this field is provided for differentiation. Usually, you do not need to use this field.
rsbuild.build
Perform a production build.
type BuildOptions = {
mode?: 'development' | 'production';
watch?: boolean;
// custom Compiler object
compiler?: Compiler | MultiCompiler;
};
function Build(options?: BuildOptions): Promise<void>;
import { logger } from '@rsbuild/core';
// build
await rsbuild.build();
// build and handle the error
try {
await rsbuild.build();
} catch (err) {
logger.error('Failed to build.');
logger.error(err);
process.exit(1);
}
Development environment build
If you need to perform a development build, you can set the mode option to 'development'.
await rsbuild.build({
mode: 'development',
});
Monitor file changes
If you need to watch file changes and re-build, you can set the watch option to true.
await rsbuild.build({
watch: true,
});
Custom Compiler
In some cases, you may want to use a custom compiler:
import { rspack } from '@rsbuild/core';
const compiler = rspack({
// ...
});
await rsbuild.build({
compiler,
});
rsbuild.startDevServer
Start the local dev server.
type StartDevServerOptions = {
// custom Compiler object
compiler?: Compiler | MultiCompiler;
// Whether to get the port silently, the default is false
getPortSilently?: boolean;
};
type StartServerResult = {
urls: string[];
port: number;
server: Server;
};
function StartDevServer(
options?: StartDevServerOptions,
): Promise<StartServerResult>;
Start Dev Server:
import { logger } from '@rsbuild/core';
// Start dev server
await rsbuild.startDevServer();
// Start dev server and handle the error
try {
await rsbuild.startDevServer();
} catch (err) {
logger.error('Failed to start dev server.');
logger.error(err);
process.exit(1);
}
After successfully starting Dev Server, you can see the following logs:
> Local: http://localhost:3000
> Network: http://192.168.0.1:3000
startDevServer returns the following parameters:
urls: URLs to access dev server.port: The actual listening port number.server: Server instance object.
const { urls, port, server } = await rsbuild.startDevServer();
console.log(urls); // ['http://localhost:3000', 'http://192.168.0.1:3000']
console.log(port); // 3000
// Close the dev server
await server.close();
Custom Compiler
In some cases, you may want to use a custom compiler:
import { rspack } from '@rsbuild/core';
const compiler = rspack({
// ...
});
await rsbuild.startDevServer({
compiler,
});
Get Port Silently
In some cases, the default startup port number is already occupied. In this situation, Rsbuild will automatically increment the port number until it finds an available one. This process will output a prompt log. If you do not want this log, you can set getPortSilently to true.
await rsbuild.startDevServer({
getPortSilently: true,
});
rsbuild.createDevServer
Rsbuild comes with a built-in dev server designed to improve the development experience. When you run the rsbuild dev command, the server will start, providing features such as page preview, routing, and hot module reloading.
If you want to integrate Rsbuild dev server into an custom server, you can use this method to get the instance methods of Rsbuild dev server and call them on demand.
type RsbuildDevServer = {
/** start the Rsbuild DevServer */
listen: () => Promise<{
urls: string[];
port: number;
server: Server;
}>;
/** The following APIs will be used when you use a custom server */
/**
* The resolved port
*
* By default, Rsbuild Server listens on port `3000` and automatically increments the port number when the port is occupied.
*/
port: number;
/**
* connect app instance.
*
* Can be used to attach custom middlewares to the dev server.
*/
middlewares: Middlewares;
/** Notify Rsbuild that the custom server has started */
afterListen: () => Promise<void>;
/** Subscribe to the http upgrade event */
onHTTPUpgrade: UpgradeEvent;
/** close the Rsbuild DevServer */
close: () => Promise<void>;
};
type CreateDevServerOptions = {
/** Custom Compiler */
compiler?: Compiler | MultiCompiler;
/** Whether to get the port silently, the default is false */
getPortSilently?: boolean;
/** Whether to trigger Rsbuild compilation, the default is true */
runCompile?: boolean;
};
function CreateDevServer(
options?: CreateDevServerOptions,
): Promise<RsbuildDevServer>;
Here is an example with express:
import { createRsbuild } from '@rsbuild/core';
import express from 'express';
export async function startDevServer() {
// Init Rsbuild
const rsbuild = await createRsbuild({});
const app = express();
// Create Rsbuild DevServer instance
const rsbuildServer = await rsbuild.createDevServer();
// Apply Rsbuild’s built-in middlewares
app.use(rsbuildServer.middlewares);
const httpServer = app.listen(rsbuildServer.port, async () => {
// Notify Rsbuild that the custom server has started
await rsbuildServer.afterListen();
});
// Subscribe to the server's http upgrade event to handle WebSocket upgrades
httpServer.on('upgrade', rsbuildServer.onHTTPUpgrade);
}
For detailed usage, please refer to: Example.
If you want to use Rsbuild DevServer to start the project directly, you can use the Rsbuild - startDevServer method directly. startDevServer is actually syntactic sugar for the following code:
const server = await rsbuild.createDevServer();
await server.listen();
rsbuild.preview
Start a server to preview the production build locally. This method should be executed after rsbuild.build.
type StartServerResult = {
urls: string[];
port: number;
server: Server;
};
function server(): Promise<StartServerResult>;
Start the server:
import { logger } from '@rsbuild/core';
// Start preview server
await rsbuild.preview();
// Start preview server and handle the error
try {
await rsbuild.preview();
} catch (err) {
logger.error('Failed to start preview server.');
logger.error(err);
process.exit(1);
}
preview returns the following parameters:
urls: URLs to access server.port: The actual listening port number.server: Server instance object.
const { urls, port, server } = await rsbuild.preview();
console.log(urls); // ['http://localhost:3000', 'http://192.168.0.1:3000']
console.log(port); // 3000
// Close the server
await server.close();
rsbuild.createCompiler
Create a Compiler object.
When the target option of createRsbuild contains only one value, the return value is Compiler; when target contains multiple values, the return value is MultiCompiler.
function CreateCompiler(): Promise<Compiler | MultiCompiler>;
const compiler = await rsbuild.createCompiler();
In most scenarios, you do not need to use this API unless you need to custom the Dev Server or other advanced scenarios.
rsbuild.addPlugins
Register one or more Rsbuild plugins, which can be called multiple times.
This method needs to be called before compiling. If it is called after compiling, it will not affect the compilation result.
type AddPluginsOptions = { before?: string } | { after?: string };
function AddPlugins(
plugins: RsbuildPlugins[],
options?: AddPluginsOptions,
): Promise<void>;
rsbuild.addPlugins([pluginFoo(), pluginBar()]);
// Insert before the bar plugin
rsbuild.addPlugins([pluginFoo()], { before: 'bar' });
// Insert after the bar plugin
rsbuild.addPlugins([pluginFoo()], { after: 'bar' });
rsbuild.getPlugins
Get all the Rsbuild plugins registered in the current Rsbuild instance.
function GetPlugins(): RsbuildPlugin[];
console.log(rsbuild.getPlugins());
rsbuild.removePlugins
Removes one or more Rsbuild plugins, which can be called multiple times.
This method needs to be called before compiling. If it is called after compiling, it will not affect the compilation result.
function RemovePlugins(pluginNames: string[]): void;
// add plugin
const pluginFoo = pluginFoo();
rsbuild.addPlugins(pluginFoo);
// remove plugin
rsbuild.removePlugins([pluginFoo.name]);
rsbuild.isPluginExists
Determines whether a plugin has been registered.
function IsPluginExists(pluginName: string): boolean;
rsbuild.addPlugins([pluginFoo()]);
rsbuild.isPluginExists(pluginFoo().name); // true
rsbuild.initConfigs
The initConfigs method is used to initialize the internal configs of Rsbuild and return the Rspack config generated internally by Rsbuild.
Usually, you do not need to call the initConfigs method, because it will be automatically called when methods such as rsbuild.build, rsbuild.startDevServer are called.
function InitConfigs(): Promise<{
rspackConfigs: RspackConfig[];
}>;
const { rspackConfigs } = await rsbuild.initConfigs();
console.log(rspackConfigs);
rsbuild.inspectConfig
The inspectConfig method is typically used for debugging the internal configuration of Rsbuild. It returns the internally generated Rsbuild config and Rspack config, serializes them into strings, and supports writing them to the disk.
If you need to view the Rsbuild and Rspack configurations during the build process, you can use debug mode, or obtain them through hooks such as onBeforeBuild, onBeforeCreateCompile.
type InspectConfigOptions = {
// View the config in the specified environment
// defaults to "development", can be set to "production"
env?: RsbuildMode;
// Whether to enable verbose mode, display the complete content of the function in the config
// defaults to `false`
verbose?: boolean;
// Specify the output path
// defaults to the value configured by `output.distPath.root`
outputPath?: string;
// Whether to write the result to disk
// defaults to `false`
writeToDisk?: boolean;
};
async function InspectConfig(options?: InspectConfigOptions): Promise<{
rsbuildConfig: string;
bundlerConfigs: string[];
origin: {
rsbuildConfig: RsbuildConfig;
bundlerConfigs: BundlerConfigs[];
};
}>;
Get the config content in string format:
const { rsbuildConfig, bundlerConfigs } = await rsbuild.inspectConfig();
console.log(rsbuildConfig, bundlerConfigs);
Write the config content to disk:
await rsbuild.inspectConfig({
writeToDisk: true,
});
rsbuild.onBeforeCreateCompiler
onBeforeCreateCompiler is a callback function that is triggered after the Compiler instance has been created, but before the build process begins. This hook is called when you run rsbuild.startDevServer, rsbuild.build, or rsbuild.createCompiler.
You can access the Rspack configuration array through the bundlerConfigs parameter. The array may contain one or more Rspack configurations, depending on the value of the Rsbuild's output.targets configuration.
function OnBeforeCreateCompiler(
callback: (params: {
bundlerConfigs: WebpackConfig[] | RspackConfig[];
}) => Promise<void> | void,
): void;
rsbuild.onBeforeCreateCompiler(({ bundlerConfigs }) => {
console.log('the Rspack config is ', bundlerConfigs);
});
rsbuild.onAfterCreateCompiler
onAfterCreateCompiler is a callback function that is triggered after the compiler instance has been created, but before the build process. This hook is called when you run rsbuild.startDevServer, rsbuild.build, or rsbuild.createCompiler.
You can access the Compiler instance through the compiler parameter:
function OnAfterCreateCompiler(callback: (params: {
compiler: Compiler | MultiCompiler;
}) => Promise<void> | void;): void;
rsbuild.onAfterCreateCompiler(({ compiler }) => {
console.log('the compiler is ', compiler);
});
rsbuild.onBeforeBuild
onBeforeBuild is a callback function that is triggered before the production build is executed.
You can access the Rspack configuration array through the bundlerConfigs parameter. The array may contain one or more Rspack configurations, depending on the value of the Rsbuild's output.targets configuration.
function OnBeforeBuild(
callback: (params: {
bundlerConfigs?: WebpackConfig[] | RspackConfig[];
}) => Promise<void> | void,
): void;
rsbuild.onBeforeBuild(({ bundlerConfigs }) => {
console.log('the Rspack config is ', bundlerConfigs);
});
rsbuild.onAfterBuild
onAfterBuild is a callback function that is triggered after running the production build. You can access the build result information via the stats parameter:
Moreover, you can use isFirstCompile to determine whether it is the first build on watch mode.
function OnAfterBuild(
callback: (params: {
isFirstCompile: boolean;
stats?: Stats | MultiStats;
}) => Promise<void> | void,
): void;
rsbuild.onAfterBuild(({ stats }) => {
console.log(stats?.toJson());
});
rsbuild.onBeforeStartDevServer
Called before starting the dev server.
function OnBeforeStartDevServer(callback: () => Promise<void> | void): void;
rsbuild.onBeforeStartDevServer(() => {
console.log('before start!');
});
rsbuild.onAfterStartDevServer
Called after starting the dev server, you can get the port number with the port parameter, and the page routes info with the routes parameter.
type Routes = Array<{
entryName: string;
pathname: string;
}>;
function OnAfterStartDevServer(
callback: (params: { port: number; routes: Routes }) => Promise<void> | void,
): void;
rsbuild.onAfterStartDevServer(({ port, routes }) => {
console.log('this port is: ', port);
console.log('this routes is: ', routes);
});
rsbuild.onCloseDevServer
Called when close the dev server.
function onCloseDevServer(callback: () => Promise<void> | void): void;
rsbuild.onCloseDevServer(async () => {
console.log('close dev server!');
});
rsbuild.onBeforeStartProdServer
Called before starting the production preview server.
function OnBeforeStartProdServer(callback: () => Promise<void> | void): void;
rsbuild.onBeforeStartProdServer(() => {
console.log('before start!');
});
rsbuild.onAfterStartProdServer
Called after starting the production preview server, you can get the port number with the port parameter, and the page routes info with the routes parameter.
type Routes = Array<{
entryName: string;
pathname: string;
}>;
function OnAfterStartProdServer(
callback: (params: { port: number; routes: Routes }) => Promise<void> | void,
): void;
rsbuild.onAfterStartProdServer(({ port, routes }) => {
console.log('this port is: ', port);
console.log('this routes is: ', routes);
});
rsbuild.onDevCompileDone
Called after each development environment build, you can use isFirstCompile to determine whether it is the first build.
function OnDevCompileDone(
callback: (params: {
isFirstCompile: boolean;
stats: Stats | MultiStats;
}) => Promise<void> | void,
): void;
rsbuild.onDevCompileDone(({ isFirstCompile }) => {
if (isFirstCompile) {
console.log('first compile!');
} else {
console.log('re-compile!');
}
});
rsbuild.onExit
Called when the process is going to exit, this hook can only execute synchronous code.
function OnExit(callback: () => void): void;
rsbuild.onExit(() => {
console.log('exit!');
});
rsbuild.getRsbuildConfig
Get the Rsbuild config, this method must be called after the modifyRsbuildConfig hook is executed.
type GetRsbuildConfig = {
(): Readonly<RsbuildConfig>;
(type: 'original' | 'current'): Readonly<RsbuildConfig>;
(type: 'normalized'): NormalizedConfig;
};
You can specify the type of Rsbuild config to read by using the type parameter:
// Get the original Rsbuild config defined by the user.
getRsbuildConfig('original');
// Get the current Rsbuild config.
// The content of this config will change at different execution stages of Rsbuild.
// For example, the content of the current Rsbuild config will be modified after running the `modifyRsbuildConfig` hook.
getRsbuildConfig('current');
// Get the normalized Rsbuild config.
// This method must be called after the `modifyRsbuildConfig` hook has been executed.
// It is equivalent to the `getNormalizedConfig` method.
getRsbuildConfig('normalized');
rsbuild.onBeforeBuild(() => {
const config = rsbuild.getRsbuildConfig();
console.log(config.html?.title);
});
rsbuild.getNormalizedConfig
Get the normalized Rsbuild config, 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.
function GetNormalizedConfig(): Readonly<NormalizedConfig>;
rsbuild.onBeforeBuild(() => {
const config = api.getNormalizedConfig();
console.log(config.html.title);
});
rsbuild.getHTMLPaths
Get path information for all HTML assets.
This method will return an object, the key is the entry name and the value is the relative path of the HTML file in the dist directory.
function GetHTMLPaths(): Record<string, string>;
rsbuild.onBeforeBuild(() => {
const htmlPaths = api.getHTMLPaths();
console.log(htmlPaths); // { main: 'html/main/index.html' };
});
