Environment API#

Here you can find all the environment related APIs.

See Multi-Environment Builds for more details.

Environment Context#

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

In Rsbuild's Plugin 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
• Example:

api.modifyRspackConfig((config, { environment }) => {
  if (environment.name === 'node') {
    // modify config for node environment
  }
  return config;
});

browserslist#

The browserslist configuration of the current environment. See Browserslist for more details.

• Type: string[]
• Example:

api.modifyRspackConfig((config, { environment }) => {
  console.log(environment.browserslist);
  return config;
});

config#

The normalized Rsbuild config for the current environment.

• Type:

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

• Example:

api.modifyRspackConfig((config, { environment }) => {
  // Rspack config
  console.log(config);
  // Rsbuild config for current environment
  console.log(environment.config);
  return config;
});

distPath#

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

• Type: string

api.modifyRspackConfig((config, { environment }) => {
  console.log(environment.distPath);
  return config;
});

entry#

The entry object from the source.entry option.

• Type:

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

• Example:

api.modifyRspackConfig((config, { environment }) => {
  console.log(environment.entry);
  return config;
});

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>;

• Example:

api.modifyRspackConfig((config, { environment }) => {
  console.log(environment.htmlPaths);
  return config;
});

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;

• Example:

api.modifyRspackConfig((config, { environment }) => {
  console.log(environment.tsconfigPath);
  return config;
});

Environment API#

Environment API provides some APIs related to the multi-environment build.

You can use environment API via rsbuild.createDevServer() or dev.setupMiddlewares, which allows you to get the build outputs information for a specific environment in the server side.

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 bundles 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 bundle 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.