Configure Rslib#

Rslib's configuration is based on Rsbuild, which means that you can use all of Rsbuild configurations, as well as the lib configuration specific to Rslib.

Configuration Structure#

Rslib provides the lib option to configure the library outputs. It is an array, and each object is used to describe a format of the output.

For example, output ESM and CJS formats, and use es2021 syntax:

export default {
  lib: [
    { format: 'esm', syntax: 'es2021' },
    { format: 'cjs', syntax: 'es2021' },
  ],
};

Common Rsbuild Configurations#

You can set common Rsbuild configurations outside the lib field, which will be inherited by each configuration object inside the lib field.

For example, set the output.target of Rsbuild to web, which will affect the output of all lib configuration objects:

export default {
  lib: [
    { format: 'esm', syntax: 'es2021' },
    { format: 'cjs', syntax: 'es2021' },
  ],
  output: {
    target: 'web',
  },
};

Separate Rsbuild Configurations#

In the lib field, you can set separate Rsbuild configurations for each output format, which will override the common Rsbuild configurations outside the lib field.

For example, separately set the output.target of the ESM output to web:

export default {
  lib: [
    // The target of the ESM output is `web`
    {
      format: 'esm',
      output: {
        target: 'web',
      },
    },
    // The CJS output inherits the common configuration and target is `node`
    {
      format: 'cjs',
    },
  ],
  output: {
    target: 'node',
  },
};

Rslib will generate the environments configuration of Rsbuild internally, please refer to Configuration Debug to view the final generated configuration.

You can also refer to the Configuration Overview page to view the detailed introduction of all configurations.

Configuration File#

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#

Rslib allows you to use most of the Rsbuild configurations. Currently, the environments config is not supported because it is generated internally by Rslib.

• Refer to Rsbuild Configuration for common Rsbuild configurations.
• Refer to Rsbuild Documentation for all Rsbuild configurations.

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.

Here is an example of a library that sets both CJS and ESM formats:

• 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.