Environment API#

This section describes some type definitions related to Rsbuild environment API.

Environment Context#

Environment context is a read-only object that provides some context information about the current environment.

In Rsbuild's hooks, you can get the environment context object through the environment or environments parameter.

type EnvironmentContext = {
  name: string;
  browserslist: string[];
  config: NormalizedEnvironmentConfig;
  distPath: string;
  entry: RsbuildEntry;
  htmlPaths: Record<string, string>;
  tsconfigPath?: string;
};

name#

The unique name of the current environment is used to distinguish and locate the environment, corresponds to the key in the environments configuration.

• Type: string

browserslist#

The range of target browsers that the project is compatible with. See details in Browserslist.

• Type: string[]

config#

The Rsbuild environment configuration after normalization.

• Type:

type NormalizedEnvironmentConfig = DeepReadonly<{
  dev: NormalizedDevConfig;
  html: NormalizedHtmlConfig;
  tools: NormalizedToolsConfig;
  source: NormalizedSourceConfig;
  server: NormalizedServerConfig;
  output: NormalizedOutputConfig;
  plugins?: RsbuildPlugins;
  security: NormalizedSecurityConfig;
  performance: NormalizedPerformanceConfig;
  moduleFederation?: ModuleFederationConfig;
}>;

distPath#

The absolute path of the output directory, corresponding to the output.distPath.root config in RsbuildConfig.

• Type: string

entry#

The entry object from the source.entry option.

• Type:

type RsbuildEntry = Record<string, string | string[] | EntryDescription>;

htmlPaths#

The path information for all HTML assets.

This API 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.

• Type:

type htmlPaths = Record<string, string>;

tsconfigPath#

The absolute path of the tsconfig.json file, or undefined if the tsconfig.json file does not exist in current project.

• Type:

type TsconfigPath = string | undefined;

Environment API#

Environment API provides a series of APIs related to the build environment.

You can use environment API in Rsbuild DevMiddleware or Custom Server to operate the build artifacts in a specific environment.

type EnvironmentAPI = {
  [name: string]: {
    getStats: () => Promise<Stats>;
    loadBundle: <T = unknown>(entryName: string) => Promise<T>;
    getTransformedHtml: (entryName: string) => Promise<string>;
  };
};

getStats#

Get the build stats of current environment.

• Type:

type GetStats = () => Promise<Stats>;

• Example:

const webStats = await environments.web.getStats();

console.log(webStats.toJson({ all: false }));

loadBundle#

Load and execute the build artifacts on the server side. This method returns the exports of the entry module.

• Type:

/**
 * @param entryName - Entry name, corresponding to a key in Rsbuild `source.entry`
 * @returns The return value of the entry module
 */
type LoadBundle = <T = unknown>(entryName: string) => Promise<T>;

• Example:

// Load the build artifacts of main entry
const result = await environments.node.loadBundle('main');

getTransformedHtml#

Get the HTML template content after compilation and transformation.

• Type:

type GetTransformedHtml = (entryName: string) => Promise<string>;

• Example:

// Get the HTML content of main entry
const html = await environments.web.getTransformedHtml('main');

This method returns the complete HTML string, including all resources and content injected through HTML plugins.