This div is used to preload the font

简体中文

Rsbuild Core

本章节描述了 Rsbuild 提供的一些核心方法。

createRsbuild

创建一个 Rsbuild 实例对象。

类型：

function createRsbuild(options: CreateRsbuildOptions): Promise<RsbuildInstance>;

示例：

import { createRsbuild } from '@rsbuild/core';

const rsbuild = await createRsbuild({
  // options
});

options

createRsbuild 的第一个参数是一个配置对象，你可以传入以下选项：

type CreateRsbuildOptions = {
  cwd?: string;
  rsbuildConfig?: RsbuildConfig;
};

各个选项的作用：

cwd：当前执行构建的根路径，默认值为 process.cwd()
provider：用于切换底层的打包工具。
rsbuildConfig：Rsbuild 配置对象。Rsbuild 提供了丰富的配置项，允许你对构建行为进行灵活定制，你可以在配置中找到所有可用的配置项。

loadConfig

加载 Rsbuild 配置文件。

类型：

function loadConfig(params: {
  // 默认为 process.cwd()
  cwd: string;
  // 指定配置文件路径，可以为相对路径或绝对路径
  path?: string;
}): Promise<{
  content: RsbuildConfig;
  filePath: string | null;
}>;

示例：

import { loadConfig } from '@rsbuild/core';

const { content } = await loadConfig();

console.log(content); // -> Rsbuild config object

如果 cwd 目录下不存在 Rsbuild 配置文件，loadConfig 方法的返回值为 { content: {}, filePath: null }。

loadEnv

加载 .env 文件，并返回所有以 prefixes 开头的环境变量。

类型：

type LoadEnvOptions = {
  /**
   * 加载 env 文件的根路径
   * @default process.cwd()
   */
  cwd?: string;
  /**
   * 用于指定 .env.[mode] 文件的名称
   * @default process.env.NODE_ENV
   */
  mode?: string;
  /**
   * public 变量的前缀
   * @default ['PUBLIC_']
   */
  prefixes?: string[];
};

function loadEnv(options: LoadEnvOptions): {
  /** .env 文件包含的所有环境变量 */
  parsed: Record<string, string>;
  /** 所有 env 文件的绝对路径 */
  filePaths: string[];
  /** 以 prefixes 开头的环境变量 */
  publicVars: Record<string, string>;
  /** 从 `process.env` 上清除挂载的环境变量 */
  cleanup: () => void;
};

示例：

import { loadEnv, mergeRsbuildConfig } from '@rsbuild/core';

const { parsed, publicVars } = loadEnv();

const mergedConfig = mergeRsbuildConfig(
  {
    source: {
      define: publicVars,
    },
  },
  userConfig,
);

该方法也会加载 .env.local 和 .env.[mode] 等文件，详见环境变量。

mergeRsbuildConfig

用于合并多份 Rsbuild 配置对象。

mergeRsbuildConfig 函数接收多个配置对象作为参数，它会将每一个配置对象进行深层合并，自动将多个函数项合并为顺序执行的函数数组，返回一个合并后的配置对象。

类型：

function mergeRsbuildConfig(...configs: RsbuildConfig[]): RsbuildConfig;

示例：

import { mergeRsbuildConfig } from '@rsbuild/core';

const config1 = {
  dev: {
    https: false,
  },
};
const config2 = {
  dev: {
    https: true,
  },
};

const mergedConfig = mergeRsbuildConfig(config1, config2);

console.log(mergedConfig); // { dev: { https: true } }

该方法不会修改入参中的 config 对象。

logger

用于输出格式统一的日志信息，基于 rslog。

示例：

import { logger } from '@rsbuild/core';

// A gradient welcome log
logger.greet(`\n➜ Rsbuild v1.0.0\n`);

// Info
logger.info('This is a info message');

// Start
logger.start('This is a start message');

// Warn
logger.warn('This is a warn message');

// Ready
logger.ready('This is a ready message');

// Success
logger.success('This is a success message');

// Error
logger.error('This is a error message');
logger.error(new Error('This is a error message with stack'));

// Debug
logger.debug('This is a debug message');

// Same as console.log
logger.log('This is a log message');

自定义 Logger

你可以使用 logger.override 方法来覆盖默认 logger 的部分或全部方法：

import { logger } from '@rsbuild/core';

logger.override({
  log: (message) => {
    console.log(`[log] ${message}`);
  },
  info: (message) => {
    console.log(`[info] ${message}`);
  },
  warn: (message) => {
    console.warn(`[warn] ${message}`);
  },
  start: (message) => {
    console.log(`[start] ${message}`);
  },
  ready: (message) => {
    console.log(`[ready] ${message}`);
  },
  error: (message) => {
    console.error(`[error] ${message}`);
  },
  success: (message) => {
    console.error(`[success] ${message}`);
  },
  debug: (message) => {
    if (process.env.DEBUG) {
      console.log(`[debug] ${message}`);
    }
  },
});

logger.info('hello'); // [info] hello

version

当前使用的 @rsbuild/core 的版本。

类型： string
示例：

import { version } from '@rsbuild/core';

console.log(version); // 1.0.0

Rsbuild Core#

createRsbuild#

options#

loadConfig#

loadEnv#

mergeRsbuildConfig#

logger#

自定义 Logger#

version#