For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /api/javascript-api/instance.md.
close
Rslib
  • English

      • Rslib instance

      This section describes all the properties and methods on the Rslib instance object.

      rslib.build

      Runs a production build, generating production outputs and writing them to the output directory.

      • Type:
      type BuildOptions = {
  /**
   * Specify library id
   */
  lib?: string[];
  /**
   * Whether to watch for file changes and rebuild.
   *
   * @default false
   */
  watch?: boolean;
};

function Build(options?: BuildOptions): Promise<{
  /**
   * Rspack's [stats](https://rspack.rs/api/javascript-api/stats) object.
   */
  stats?: Rspack.Stats | Rspack.MultiStats;
  /**
   * Close the build and call the `onCloseBuild` hook.
   * In watch mode, this method will stop watching.
   */
  close: () => Promise<void>;
}>;
      • Example:
      // Example 1: run build
await rslib.build();

// Example 2: run build of a specified library id
await rslib.build({
  lib: ['esm'],
});

// Example 3: build and get all assets
const { stats } = await rslib.build();

if (stats) {
  const { assets } = stats.toJson({
    // exclude unused fields to improve performance
    all: false,
    assets: true,
  });
  console.log(assets);
}

      Run specified library

      You can specify the library to build using the lib option. If this option is not specified, all libraries will be built.

      See lib.id to learn how to get or set the ID of the library.

      await rslib.build({
  lib: ['cjs', 'esm'],
});

      Watch file changes

      To watch file changes and re-build, set the watch option to true.

      await rslib.build({
  watch: true,
});

      Close build

      rslib.build() returns a close() method that stops the build process.

      In watch mode, calling the close() method will stop watching:

      const buildResult = await rslib.build({
  watch: true,
});
await buildResult.close();

      In non-watch mode, also call the close() method to end the build, which triggers the onCloseBuild hook of Rsbuild for cleanup operations.

      const buildResult = await rslib.build();
await buildResult.close();

      Stats object

      In non-watch mode, rslib.build() returns an Rspack stats object.

      For example, use the stats.toJson() method to get asset information:

      const result = await rslib.build();
const { stats } = result;

if (stats) {
  const { assets } = stats.toJson({
    // exclude unused fields to improve performance
    all: false,
    assets: true,
  });
  console.log(assets);
}

      rslib.startMFDevServer

      Start the dev server for the Module Federation format library. This method will:

      1. Start a dev server to serve your application
      2. Watch for file changes and trigger recompilation
      • Type:
      type StartMFDevServerOptions = {
  /**
   * Specify library id
   */
  lib?: string[];
};

type StartServerResult = {
  /**
   * The URLs that server is listening on.
   */
  urls: string[];
  /**
   * The actual port used by the server.
   */
  port: number;
  server: {
    /**
     * Close the server.
     * In development mode, this will call the `onCloseDevServer` hook.
     */
    close: () => Promise<void>;
  };
};

function startMFDevServer(
  options?: StartMFDevServerOptions,
): Promise<StartServerResult>;
      • Example:

      Start dev server:

      // Start dev server
await rslib.startMFDevServer();

// Start dev server of a specified library id
await rslib.startMFDevServer({
  lib: ['entry1'],
});

      startMFDevServer returns these parameters:

      • urls: URLs to access dev server.
      • port: The actual listening port number.
      • server: Server instance object.
      const { port } = await rslib.startMFDevServer();
console.log(port); // 3000

      Run specified library

      You can specify the library to start dev server using the lib option.

      See lib.id to learn how to get or set the ID of the library.

      await rslib.startMFDevServer({
  lib: ['entry1'],
});

      Close server

      Call the close() method to close the dev server, trigger the onCloseDevServer hook of Rsbuild, and perform cleanup operations.

      const { server } = await rslib.startMFDevServer();
await server.close();

      rslib.inspectConfig

      Inspects and debugs Rslib's internal configurations. It provides access to:

      • The resolved Rslib configuration
      • The resolved Rsbuild configuration
      • The environment-specific Rsbuild configurations
      • The generated Rspack configurations

      The method serializes these configurations to strings and optionally writes them to disk for inspection.

      • Type:
      type InspectConfigOptions = {
  /**
   * Specify library id
   */
  lib?: string[];
  /**
   * Inspect the config in the specified mode.
   * Available options: 'development' or 'production'.
   * @default Inferred from `process.env.NODE_ENV`: 'development' when set to 'development', otherwise 'production'.
   */
  mode?: 'development' | 'production';
  /**
   * Enables verbose mode to display the complete function
   * content in the configuration.
   * @default false
   */
  verbose?: boolean;
  /**
   * Specify the output path for inspection results.
   * @default '<output.distPath.root>/.rsbuild'
   */
  outputPath?: string;
  /**
   * Whether to write the inspection results to disk.
   * @default false
   */
  writeToDisk?: boolean;
};

function inspectConfig(options?: InspectConfigOptions): Promise<{
  rslibConfig: string;
  rsbuildConfig: string;
  bundlerConfigs: string[];
  environmentConfigs: string[];
  origin: {
    rsbuildConfig: RsbuildConfig;
    environmentConfigs: Record<string, EnvironmentConfig>;
    bundlerConfigs: Rspack.Configuration[];
  };
}>;
      Tip

      To view the configurations during the build process, use debug mode, or obtain them through Rsbuild hooks such as onBeforeBuild, onBeforeCreateCompiler in Rsbuild plugins.

      • Example:

      Get the content of configs in string format:

      const { rslibConfig, rsbuildConfig, bundlerConfigs } =
  await rslib.inspectConfig();

console.log(rslibConfig, rsbuildConfig, bundlerConfigs);

      Write the config content to disk:

      await rslib.inspectConfig({
  writeToDisk: true,
});

      Setting mode

      By default, mode is inferred from process.env.NODE_ENV. When mode is 'production', rslib.inspectConfig() outputs production mode configs for all libraries. You can also set mode to 'development' to output development mode configs only for libraries with format set to mf:

      await rslib.inspectConfig({
  mode: 'development',
});
      Tip

      The Rslib config is resolved before inspectConfig() is called, so mode does not affect how it is loaded. To load different Rslib configs based on NODE_ENV, set it before calling createRslib().

      Run specified library

      You can specify the library to inspect configurations using the lib option. If this option is not specified, all libraries will be inspected.

      See lib.id to learn how to get or set the ID of the library.

      await rslib.inspectConfig({
  lib: ['cjs', 'esm'],
});

      Output path

      You can set the output path using outputPath. When writeToDisk is true, the files are written to the .rsbuild directory under output.distPath.root by default.

      If outputPath is a relative path, it will be resolved relative to output.distPath.root. You can also set outputPath to an absolute path, in which case the files will be written directly to that path. For example:

      import path from 'node:path';

await rslib.inspectConfig({
  writeToDisk: true,
  outputPath: path.join(__dirname, 'custom-dir'),
});

      rslib.getRslibConfig

      Get the Rslib config.

      • Type:
      function getRslibConfig(): Readonly<RslibConfig>;
      • Example:
      import { createRslib } from '@rslib/core';

const rslib = await createRslib();
const config = rslib.getRslibConfig();
console.log(config.lib);

      rslib.onAfterCreateRsbuild

      Called after the internal Rsbuild instance is created. You can access or call the properties and methods of the Rsbuild instance through this method.

      • Type:
      type OnAfterCreateRsbuildFn = (params: {
  rsbuild: RsbuildInstance;
}) => void | Promise<void>;

function onAfterCreateRsbuild(callback: OnAfterCreateRsbuildFn): void;
      • Example:
      const rslib = await createRslib();

rslib.onAfterCreateRsbuild(({ rsbuild }) => {
  rsbuild.onAfterBuild(() => {
    console.log('build done');
  });
});

await rslib.build();

      All properties and methods on the Rsbuild instance object can be viewed in the Rsbuild instance document.