#Configure Rslib

Rslib configuration lets you define library outputs and control how each output is built.

#Configuration structure

Rslib configuration consists of two types of options:

• Lib configurations describe library outputs, including their output formats, output structures, and syntax targets.
• Rsbuild configurations control the underlying compilation and build behavior, including module resolution, source processing, and related plugins.

The lib field is an optional array of objects. Each object corresponds to one output and can contain both types of configuration above. Configurations inside a lib item apply only to that output, while configurations outside the lib field are shared across all outputs.

Rslib merges the shared configuration with each lib item according to the configuration merge rules.

#Lib configurations

Lib configurations can be specified in a lib item to configure a specific output. Some lib configurations can also be placed outside the lib field as shared configuration for all outputs.

For example, set syntax to es2020 for the CJS output and use shared configuration to set syntax to es2021 for the other outputs:

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

After merging, syntax is es2021 for the ESM output and es2020 for the CJS output.

When you only need to generate a single ESM output using the default configuration, you can omit the lib field. This is equivalent to setting lib: [{}].

#Rsbuild configurations

Rsbuild configurations can be placed outside the lib field as shared configuration or inside a lib item to configure a specific output.

For example, set the ESM output's output.target to 'web', and use shared configuration to set output.target to 'node' for the other outputs:

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

After merging, output.target is 'web' for the ESM output and 'node' for the CJS output.

#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 --config rslib.prod.config.mjs"
  }
}

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

rslib -c rslib.prod.config.mjs

#Specify config loader

Rslib provides three ways to load configuration files:

• jiti: When you use a configuration file with the .ts, .mts, and .cts extensions, Rslib will use jiti to load configuration files, providing interoperability between ESM and CommonJS. The behavior of module resolution differs slightly from the native behavior of Node.js.

• native: Use Node.js native loader to load the configuration file. This can ensure that the module resolution behavior is consistent with the native behavior of Node.js and has better performance. This requires that your JavaScript runtime already natively supports TypeScript.

  For example, Node.js v22.6.0+ already natively supports TypeScript, you can use the following command to use the Node.js native loader to load the configuration file:

  # Node.js >= v22.18.0
  # No need to set --experimental-strip-types
  npx rslib --config-loader native
  
  # Node.js v22.6.0 - v22.17.1
  # Need to set --experimental-strip-types
  NODE_OPTIONS="--experimental-strip-types" npx rslib --config-loader native

• auto(Default): Use Node.js's native loader to load configuration files first, fallback to using jiti if it fails.

#About Node.js native loader

When using Node.js's native loader, please note the following limitations:

1. When importing JSON files, you need to use import attributes:

   import pkgJson from './package.json' with { type: 'json' }; // ✅ Correct
   import pkgJson from './package.json'; // ❌ Incorrect

2. When importing TypeScript files, you need to include the .ts extension:

   import baseConfig from './rslib.base.config.ts'; // ✅ Correct
   import baseConfig from './rslib.base.config'; // ❌ Incorrect

See Node.js - Running TypeScript Natively for more details.

#Using environment variables

In the configuration file, you can use Node.js environment variables to dynamically set different configurations:

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

export default defineConfig({
  lib: [
    {
      format: 'esm',
    },
  ],
  source: {
    alias: {
      '@language':
        process.env.LANGUAGE === 'en'
          ? './src/language/en.js'
          : './src/language/zh.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.

#Debug mode

You can add the DEBUG=rslib environment variable when building to enable Rslib's debug mode.

DEBUG=rslib pnpm build

In debug mode, Rslib will output additional log information and write the final Rsbuild config and Rspack config after processing by Rslib to the output directory, making it convenient for developers to view and debug.

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

Inspect config succeed, open following files to view the content:

  - Rsbuild Config (esm): /project/dist/.rsbuild/rsbuild.config.esm.mjs
  - Rsbuild Config (cjs): /project/dist/.rsbuild/rsbuild.config.cjs.mjs
  - Rspack Config (esm): /project/dist/.rsbuild/rspack.config.esm.mjs
  - Rspack Config (cjs): /project/dist/.rsbuild/rspack.config.cjs.mjs
  - Rslib Config: /project/dist/.rsbuild/rslib.config.mjs

• 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.
• Open the generated /dist/.rsbuild/rslib.config.mjs file to see the complete content of the Rslib config.