Rsbuild Instance
本章节描述了 Rsbuild 实例对象上所有的属性和方法。
rsbuild.context
rsbuild.context
是一个只读对象,提供一些上下文信息。
context.version
当前使用的 @rsbuild/core
版本。
context.entry
构建入口对象,对应 source.entry
选项。
type RsbuildEntry = Record<string, string | string[] | EntryDescription>;
context.targets
构建产物类型,对应调用 Rsbuild 配置里的 output.targets
选项。
type RsbuildTarget = 'web' | 'node' | 'web-worker' | 'service-worker';
type Context = {
targets: RsbuildTarget[];
};
context.rootPath
当前执行构建的根路径,对应调用 createRsbuild
时传入的 cwd
选项。
context.distPath
构建产物输出目录的绝对路径,对应 RsbuildConfig
中的 output.distPath.root
配置项。
context.cachePath
构建过程中生成的缓存文件所在的绝对路径。
context.tsconfigPath
tsconfig.json 文件的绝对路径,若项目中不存在 tsconfig.json 文件,则为 undefined
。
type TsconfigPath = string | undefined;
context.devServer
Dev Server 相关信息,包含了当前 Dev Server 的 hostname 和端口号。
type DevServer = {
hostname: string;
port: number;
};
context.bundlerType
当前执行构建的构建工具类型。
type bundlerType = 'rspack' | 'webpack';
rsbuild.build
调用 build 方法时,会执行一次生产环境构建。
type BuildOptions = {
mode?: 'development' | 'production';
watch?: boolean;
// 自定义 Compiler 对象
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);
}
开发环境构建
如果需要执行一次开发环境构建,可以将 mode
参数设置为 'development'
。
await rsbuild.build({
mode: 'development',
});
监听文件变化
如果需要自动监听文件变化并重新执行构建,可以将 watch
参数设置为 true
。
await rsbuild.build({
watch: true,
});
自定义 Compiler
个别情况下,你可能希望使用自定义的 compiler:
import { rspack } from '@rspack/core';
const compiler = rspack({
// ...
});
await rsbuild.build({
compiler,
});
rsbuild.startDevServer
启动本地 dev server。
type StartDevServerOptions = {
// 自定义 Compiler 对象
compiler?: Compiler | MultiCompiler;
// 是否在启动时静默获取端口号,默认为 false
getPortSilently?: boolean;
};
type StartServerResult = {
urls: string[];
port: number;
server: Server;
};
function StartDevServer(
options?: StartDevServerOptions,
): Promise<StartServerResult>;
启动 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);
}
成功启动 Dev Server 后,可以看到以下日志信息:
> Local: http://localhost:8080
> Network: http://192.168.0.1:8080
startDevServer
会返回以下参数:
urls
:访问 Dev Server 的 URLs
port
实际监听的端口号
server
:Server 实例对象
const { urls, port, server } = await rsbuild.startDevServer();
console.log(urls); // ['http://localhost:8080', 'http://192.168.0.1:8080']
console.log(port); // 8080
// 关闭 Dev Server
await server.close();
自定义 Compiler
个别情况下,你可能希望使用自定义的 compiler:
import { rspack } from '@rspack/core';
const compiler = rspack({
// ...
});
await rsbuild.startDevServer({
compiler,
});
静默获取端口号
某些情况下,默认启动的端口号已经被占用,此时 Rsbuild 会自动递增端口号,直至找到一个可用端口。这个过程会输出提示日志,如果你不希望这段日志,可以将 getPortSilently
设置为 true
。
await rsbuild.startDevServer({
getPortSilently: true,
});
rsbuild.preview
在本地启动 Server 来预览生产环境构建的产物,需要在 rsbuild.build
方法之后执行。
type StartServerResult = {
urls: string[];
port: number;
server: Server;
};
function server(): Promise<StartServerResult>;
启动 Server:
import { logger } from '@rsbuild/core';
// Start preview server
await rsbuild.preview();
// Start preview server and hanble the error
try {
await rsbuild.preview();
} catch (err) {
logger.error('Failed to start preview server.');
logger.error(err);
process.exit(1);
}
preview
会返回以下参数:
urls
:访问 Server 的 URLs
port
实际监听的端口号
server
:Server 实例对象
const { urls, port, server } = await rsbuild.preview();
console.log(urls); // ['http://localhost:8080', 'http://192.168.0.1:8080']
console.log(port); // 8080
// 关闭 Server
await server.close();
rsbuild.createCompiler
创建一个 compiler 对象。
当 createRsbuild
的 target
选项包含一个值时,返回值为 Compiler
;当 target
包含多个值时,返回值为 MultiCompiler
。
function CreateCompiler(): Promise<Compiler | MultiCompiler>;
const compiler = await rsbuild.createCompiler();
大部分场景下,不需要使用该 API,除非需要进行自定义 Dev Server 等高级操作。
rsbuild.addPlugins
注册一个或多个 Rsbuild 插件,可以被多次调用。
该方法需要在开始编译前调用,如果在开始编译之后调用,则不会影响编译结果。
type AddPluginsOptions = { before?: string } | { after?: string };
function AddPlugins(
plugins: RsbuildPlugins[],
options?: AddPluginsOptions,
): Promise<void>;
rsbuild.addPlugins([pluginFoo(), pluginBar()]);
// 在 bar 插件之前插入
rsbuild.addPlugins([pluginFoo()], { before: 'bar' });
// 在 bar 插件之后插入
rsbuild.addPlugins([pluginFoo()], { after: 'bar' });
rsbuild.removePlugins
移除一个或多个 Rsbuild 插件,可以被多次调用。
该方法需要在开始编译前调用,如果在开始编译之后调用,则不会影响编译结果。
function RemovePlugins(pluginNames: string[]): void;
// 添加插件
const pluginFoo = pluginFoo();
rsbuild.addPlugins(pluginFoo);
// 移除插件
rsbuild.removePlugins([pluginFoo.name]);
rsbuild.isPluginExists
判断某个插件是否已经被注册。
function IsPluginExists(pluginName: string): boolean;
rsbuild.addPlugins([pluginFoo()]);
rsbuild.isPluginExists(pluginFoo().name); // true
rsbuild.inspectConfig
查看 Rsbuild 内部最终生成的 Rsbuild 配置和 bundler 配置。
TIP
inspectConfig
方法不支持与 startDevServer
/ build
方法同时使用。
当你需要在构建过程中查看完整的 Rsbuild 和 bundler 配置时,可以使用 调试模式,也可以通过 onBeforeBuild
、onBeforeCreateCompile
等钩子函数来获取。
type InspectConfigOptions = {
// 查看指定环境下的配置,默认为 "development",可以设置为 "production"
env?: RsbuildMode;
// 是否开启冗余模式,展示配置中函数的完整内容,默认为 `false`
verbose?: boolean;
// 指定输出路径,默认为 `output.distPath.root` 配置的值
outputPath?: string;
// 是否将结果写入到磁盘中,默认为 `false`
writeToDisk?: boolean;
};
async function InspectConfig(options?: InspectConfigOptions): Promise<{
rsbuildConfig: string;
bundlerConfigs: string[];
origin: {
rsbuildConfig: RsbuildConfig;
bundlerConfigs: BundlerConfigs[];
};
}>;
拿到字符串格式的 Config 内容:
const { rsbuildConfig, bundlerConfigs } = await rsbuild.inspectConfig();
console.log(rsbuildConfig, bundlerConfigs);
直接将配置内容写入到磁盘上:
await rsbuild.inspectConfig({
writeToDisk: true,
});
rsbuild.onBeforeCreateCompiler
onBeforeCreateCompiler
是在创建底层 Compiler 实例前触发的回调函数,当你执行 rsbuild.startDevServer
、rsbuild.build
或 rsbuild.createCompiler
时,都会调用此钩子。
你可以通过 bundlerConfigs
参数获取到底层打包工具的最终配置数组:
- 如果当前打包工具为 Rspack,则获取到的是 Rspack 配置数组。
- 如果当前打包工具为 webpack,则获取到的是 webpack 配置数组。
- 配置数组中可能包含一份或多份配置,这取决于你是否开启了 SSR 等功能。
你可以通过 bundlerConfigs
参数获取到底层打包工具的最终配置对象。
function OnBeforeCreateCompiler(
callback: (params: {
bundlerConfigs: WebpackConfig[] | RspackConfig[];
}) => Promise<void> | void,
): void;
rsbuild.onBeforeCreateCompiler(({ bundlerConfigs }) => {
console.log('the bundler config is ', bundlerConfigs);
});
rsbuild.onAfterCreateCompiler
onAfterCreateCompiler
是在创建 Compiler 实例后、执行构建前触发的回调函数,当你执行 rsbuild.startDevServer
、rsbuild.build
或 rsbuild.createCompiler
时,都会调用此钩子。
你可以通过 compiler
参数获取到 Compiler 实例对象:
function OnAfterCreateCompiler(callback: (params: {
compiler: Compiler | MultiCompiler;
}) => Promise<void> | void;): void;
rsbuild.onAfterCreateCompiler(({ compiler }) => {
console.log('the compiler is ', compiler);
});
rsbuild.onBeforeBuild
onBeforeBuild
是在执行生产环境构建前触发的回调函数,你可以通过 bundlerConfigs
参数获取到底层打包工具的最终配置数组:
-
如果当前打包工具为 Rspack,则获取到的是 Rspack 配置数组。
-
如果当前打包工具为 webpack,则获取到的是 webpack 配置数组。
-
配置数组中可能包含一份或多份配置,这取决于 Rsbuild 当前 target 配置的值。
-
类型:
function OnBeforeBuild(
callback: (params: {
bundlerConfigs?: WebpackConfig[] | RspackConfig[];
}) => Promise<void> | void,
): void;
rsbuild.onBeforeBuild(({ bundlerConfigs }) => {
console.log('the bundler config is ', bundlerConfigs);
});
rsbuild.onAfterBuild
onAfterBuild
是在执行生产环境构建后触发的回调函数,你可以通过 stats
参数获取到构建结果信息:
function OnAfterBuild(
callback: (params: { stats?: Stats | MultiStats }) => Promise<void> | void,
): void;
rsbuild.onAfterBuild(({ stats }) => {
console.log(stats?.toJson());
});
rsbuild.onBeforeStartDevServer
在启动开发服务器前调用。
function OnBeforeStartDevServer(callback: () => Promise<void> | void): void;
rsbuild.onBeforeStartDevServer(() => {
console.log('before start!');
});
rsbuild.onAfterStartDevServer
在启动开发服务器后调用。你可以通过 port
参数获得开发服务器监听的端口号,通过 routes
获得页面路由信息。
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
关闭开发服务器时调用。
function onCloseDevServer(callback: () => Promise<void> | void): void;
rsbuild.onCloseDevServer(async () => {
console.log('close dev server!');
});
rsbuild.onBeforeStartProdServer
在启动生产预览服务器前调用。
function OnBeforeStartProdServer(callback: () => Promise<void> | void): void;
rsbuild.onBeforeStartProdServer(() => {
console.log('before start!');
});
rsbuild.onAfterStartProdServer
在启动生产预览服务器后调用,你可以通过 port
参数获得生产服务器监听的端口号,通过 routes
获得页面路由信息。
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
在每次开发环境构建结束后调用,你可以通过 isFirstCompile
来判断是否为首次构建。
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
在进程即将退出时调用,这个钩子只能执行同步代码。
function OnExit(callback: () => void): void;
rsbuild.onExit(() => {
console.log('exit!');
});
rsbuild.getRsbuildConfig
获取 Rsbuild 配置。
type GetRsbuildConfig = {
(): Readonly<RsbuildConfig>;
(type: 'original' | 'current'): Readonly<RsbuildConfig>;
(type: 'normalized'): NormalizedConfig;
};
你可以通过 type
参数来指定读取的 Rsbuild 配置类型:
// 获取用户定义的原始 Rsbuild 配置。
getRsbuildConfig('original');
// 获取当前的 Rsbuild 配置。
// 在 Rsbuild 的不同执行阶段,该配置的内容会发生变化。
// 比如 `modifyRsbuildConfig` 钩子执行后会修改当前 Rsbuild 配置的内容。
getRsbuildConfig('current');
// 获取归一化后的 Rsbuild 配置。
// 该方法必须在 `modifyRsbuildConfig` 钩子执行完成后才能被调用。
// 等价于 `getNormalizedConfig` 方法。
getRsbuildConfig('normalized');
rsbuild.onBeforeBuild(() => {
const config = api.getRsbuildConfig();
console.log(config.html?.title);
});
rsbuild.getNormalizedConfig
获取归一化后的 Rsbuild 配置,该方法必须在 modifyRsbuildConfig
钩子执行完成后才能被调用。
相较于 getRsbuildConfig
方法,该方法返回的配置经过了归一化处理,配置的类型定义会得到收敛,比如 config.html
的 undefined
类型将被移除。
推荐优先使用该方法获取配置。
function GetNormalizedConfig(): Readonly<NormalizedConfig>;
rsbuild.onBeforeBuild(() => {
const config = api.getNormalizedConfig();
console.log(config.html.title);
});
rsbuild.getHTMLPaths
获取所有 HTML 产物的路径信息。
该方法会返回一个对象,对象的 key 为 entry 名称,value 为 HTML 文件在产物目录下的相对路径。
function GetHTMLPaths(): Record<string, string>;
rsbuild.onBeforeBuild(() => {
const htmlPaths = api.getHTMLPaths();
console.log(htmlPaths); // { main: 'html/main/index.html' };
});