> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 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](/config/lib.md) describe library outputs, including their output formats, output structures, and syntax targets.
- [Rsbuild configurations](/config/rsbuild.md) 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 top-level configurations shared across `lib` outputs.

Rslib merges the top-level configuration with each `lib` item according to the [configuration merge rules](https://rsbuild.rs/api/javascript-api/core#merge-rules).

### Lib configurations

Lib configurations can be specified in a `lib` item to configure a specific output. [Some lib configurations](/config/lib.md#top-level-lib-configurations) can also be placed outside the `lib` field as top-level configuration shared across `lib` outputs.

For example, set [`syntax`](/config/lib/syntax.md) to `es2020` for the CJS output and use top-level configuration to set `syntax` to `es2021` for the other outputs:

```js title="rslib.config.mjs"
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 top-level configuration shared across `lib` outputs, or inside a `lib` item to configure a specific output.

For example, set the ESM output's [output.target](/config/rsbuild/output.md#outputtarget) to `'web'`, and use top-level configuration to set `output.target` to `'node'` for the other outputs:

```js title="rslib.config.mjs"
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.

:::info

- Rslib generates the Rsbuild [environments](https://rsbuild.rs/config/environments) configuration internally. You can enable [debug mode](#debug-mode) or run the [rslib inspect](/guide/basic/cli.md#rslib-inspect) command to view the final generated configuration.

- You can find detailed descriptions of all configuration options on the [Configuration overview](/config/index.md) page.

:::

## 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](/config/lib/syntax.md) configuration and the Rsbuild [output.target](https://rsbuild.rs/config/output/target#outputtarget) configuration:

```ts title="rslib.config.ts"
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.

:::tip

When you use the `.ts`, `.mts`, and `.cts` extensions, Rslib will use [jiti](https://github.com/unjs/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.

:::

## 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`:

```json title="package.json"
{
  "scripts": {
    "build": "rslib --config rslib.prod.config.mjs"
  }
}
```

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

```bash
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](https://github.com/unjs/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:

  ```bash
  # 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:

   ```ts
   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:

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

> See [Node.js - Running TypeScript Natively](https://nodejs.org/en/learn/typescript/run-natively#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:

```ts title="rslib.config.ts"
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](/config/rsbuild/index.md) for common Rsbuild configurations.
- Refer to [Rsbuild Documentation](https://rsbuild.rs/config/) 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](https://rsbuild.rs/guide/configuration/rspack).

## Debug mode

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

```bash
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.