Configure Rslib#

Rslib provides a wide range of configuration options and sets a common default value for each option, which can meet the requirements of most use cases. Therefore, in most cases, you can use Rslib out of the box with few configurations.

If you need to customize build behaviors, you can read the following sections to learn about the configuration options and its usage.

Configuration Structure#

The configuration structure of Rslib looks like this:

export default {
  // Array of Lib configurations.
  // Each object represents a set of independent configurations for each output format.
  // Distinct configurations can be specified in each object, which is a superset of Rsbuild configurations along with Rslib's specific configurations.
  lib: [
    // The first set of Lib configurations
    {
      // Independent Rslib specific configurations
      format: 'esm', // options for the output format of JavaScript files
      bundle: true, // options for the build type
      autoExtension: true, // options for the extensions of JavaScript files
      syntax: 'esnext', // options for the target syntax
      externalHelpers: false, // options for externalizing helper functions
      umdName: 'RslibUmdExample', // options for the export name of the UMD library
      autoExternal: {
        // options for automatically externalizing third-party dependencies
      },
      redirect: {
        // options for redirecting import paths
      },
      dts: {
        // options for generating TypeScript declaration files
      },
      shims: {
        // options for compatibility shims
      },
      banner: {
        // options for the file banner
      },
      footer: {
        // options for the file footer
      },
      // Independent Rsbuild configurations
      output: {
        // options for build outputs
      },
      source: {
        // options for source code parsing and compilation
      },
      tools: {
        // options for the low-level tools
      },
      plugins: [
        // configure Rsbuild plugins
      ],
      // other independent Rsbuild configurations
    },
    {
      // The second set of Lib configurations
      format: 'cjs',
      // ... other independent Rslib specific configurations and Rsbuild configurations
    },
    // ... Additional sets of Lib configurations (if needed)
  ],
  // Shared Rsbuild configurations
  output: {
    // options for build outputs
  },
  source: {
    // options for source code parsing and compilation
  },
  tools: {
    // options for the low-level tools
  },
  plugins: [
    // configure Rsbuild plugins
  ],
  // ... other Rsbuild configurations
};

The configuration file exports a default object that includes a lib array and shared Rsbuild configuration options. You can find detailed descriptions of all configs on the Configure Overview page.

• Lib Configurations (at least one object is required): The lib array contains multiple objects, each representing a set of independent configurations that will generate different outputs. Each object within the lib array can specify unique configurations, which is a superset of Rsbuild configurations along with Rslib's specific configurations.
• Shared Rsbuild Configurations (optional): Outside the lib array, there are shared Rsbuild configuration options that will be deep merged with independent Rsbuild configuration of each lib configuration object.

Rslib generates corresponding Rsbuild environments configurations based on the multiple build configurations of different output formats. You can view the final generated configurations through the configuration debug documentation.

Configuration Usage#

When you use the CLI of Rslib, Rslib will automatically read the configuration file in the root directory of the current project and resolve it in the following order:

• rslib.config.mjs
• rslib.config.ts
• rslib.config.js
• rslib.config.cjs
• rslib.config.mts
• rslib.config.cts

We recommend using the .mjs or .ts format for the configuration file and importing the defineConfig utility function from @rslib/core. It provides friendly TypeScript type hints and autocompletion, which can help you avoid errors in the configuration.

For example, in rslib.config.ts, you can define the Rslib syntax configuration and the Rsbuild output.target configuration:

import { defineConfig } from '@rslib/core';

export default defineConfig({
  lib: [
    {
      format: 'esm',
      syntax: 'es2021',
    },
  ],
  output: {
    target: 'node',
  },
});

If you are developing a non-TypeScript project, you can use the .mjs format for the configuration file.

Specify Config File#

Rslib CLI uses the --config option to specify the config file, which can be set to a relative path or an absolute path.

For example, if you need to use the rslib.prod.config.mjs file when running build, you can add the following scripts to package.json:

{
  "scripts": {
    "build": "rslib build --config rslib.prod.config.mjs"
  }
}

You can also abbreviate the --config option to -c:

rslib build -c rslib.prod.config.mjs

Using Environment Variables#

In the configuration file, you can use Node.js environment variables such as process.env.NODE_ENV to dynamically set different configurations:

import { defineConfig } from '@rslib/core';

export default defineConfig({
  lib: [
    {
      format: 'esm',
    },
  ],
  source: {
    alias: {
      '@request':
        process.env.NODE_ENV === 'development'
          ? './src/request.dev.js'
          : './src/request.prod.js',
    },
  },
});

Configure Rsbuild#

In Rslib project, you can configure Rsbuild related configurations in both lib configuration object and shared configuration section.

Common-used Rsbuild configurations in library development are listed at Rsbuild Configuration.

You can also refer to the Rsbuild Configuration for checking the complete configuration items.

Configure Rspack#

Rslib is built on top of Rsbuild and Rsbuild supports directly modifying the Rspack configuration object and also supports modifying the built-in Rspack configuration of Rsbuild through rspack-chain. This means you can configure Rspack related configurations in an Rslib project as well.

For more details, refer to Configure Rspack.

Configuration Debug#

You can enable Rslib's debug mode by adding the DEBUG=rsbuild environment variable when executing a build. It will display the final Rsbuild/Rspack configuration after processing by Rslib.

DEBUG=rsbuild pnpm build

In debug mode, Rslib will write the Rsbuild / Rspack config to the dist directory, which is convenient for developers to view and debug.

Below is an example of a configuration for Rslib that builds both CJS and ESM output.

• Open the generated /dist/.rsbuild/rsbuild.config.esm.mjs file to see the complete content of the Rsbuild config.
• Open the generated /dist/.rsbuild/rspack.config.esm.mjs file to see the complete content of the Rspack config.