#配置 Rslib

通过 Rslib 配置，你可以定义库的产物形式，并控制每份产物的构建行为。

#配置结构

Rslib 配置由两类配置组成：

• lib 配置：描述库产物本身，包括输出格式、产物结构和语法目标等。
• Rsbuild 配置：控制底层编译和构建行为，包括模块解析、源码处理与相关插件等。

lib 是一个可选的对象数组，每个对象对应一份产物，可包含上述两类配置。写在 lib 项中的配置仅作用于对应产物；写在 lib 字段外的配置则作为顶层配置，在各个 lib 产物之间共享。

Rslib 会按照 配置合并规则 将顶层配置与每个 lib 项合并。

#lib 配置

lib 配置可以写在 lib 项中，用于单独配置对应产物。部分 lib 配置也可以写在 lib 字段外作为顶层配置，在各个 lib 产物之间共享。

例如，将 CJS 产物的 syntax 设置为 es2020，并通过顶层配置将其余产物的 syntax 设置为 es2021：

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

合并后，ESM 产物的 syntax 为 es2021，CJS 产物的 syntax 为 es2020。

当你只需要基于默认配置生成一份 ESM 产物时，可以省略 lib 字段，这等价于配置 lib: [{}]。

#Rsbuild 配置

Rsbuild 配置可以写在 lib 字段外作为顶层配置，在各个 lib 产物之间共享；也可以写在 lib 项中，用于单独配置对应产物。

例如，将 ESM 产物的 output.target 设置为 'web'，并通过顶层配置将其余产物的 output.target 设置为 'node'：

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

合并后，ESM 产物的 output.target 为 'web'，CJS 产物的 output.target 为 'node'。

#配置文件

当你使用 Rslib 的 CLI 命令时，Rslib 会自动读取当前项目根目录下的配置文件，按照以下顺序进行解析：

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

我们推荐使用 .mjs 或 .ts 格式的配置文件，并从 @rslib/core 中导入 defineConfig 工具函数, 它提供了友好的 TypeScript 类型推导和自动补全，可以帮助你避免配置中的错误。

比如在 rslib.config.ts 中，你可以定义 Rslib 的 syntax 配置和 Rsbuild 的 output.target 配置：

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

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

如果你在开发一个非 TypeScript 项目，可以使用 .mjs 格式的配置文件。

#指定配置文件

Rslib CLI 通过 --config 选项来指定配置文件，可以设置为相对路径或绝对路径。

例如，你需要在执行 build 命令时使用 rslib.prod.config.mjs 文件，可以在 package.json 中添加如下配置：

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

你也可以将 --config 选项缩写为 -c：

rslib -c rslib.prod.config.mjs

#指定加载方式

Rslib 提供了三种配置文件加载方式：

• jiti：当你使用 .ts, .mts 和 .cts 后缀的配置文件时，Rslib 会使用 jiti 来加载配置文件，提供 ESM 与 CommonJS 的互操作性，模块解析的行为与 Node.js 原生行为存在一定差异。

• native：使用 Node.js 原生 loader 来加载配置文件，这可以保证模块解析的行为与 Node.js 原生行为一致，并且性能更好。这要求你使用的 JavaScript 运行时已经原生支持 TypeScript。

  例如，Node.js 从 v22.6.0 开始已经原生支持 TypeScript，你可以运行如下命令来使用 Node.js 原生 loader 来加载配置文件：

  # Node.js >= v22.18.0
  # 不需要设置 --experimental-strip-types
  npx rslib --config-loader native
  
  # Node.js v22.6.0 - v22.17.1
  # 需要设置 --experimental-strip-types
  NODE_OPTIONS="--experimental-strip-types" npx rslib --config-loader native

• auto（默认）：优先使用 Node.js 原生 loader 来加载配置文件，失败时回退到使用 jiti 加载。

#关于 Node.js 原生 loader

使用 Node.js 原生 loader 时，请注意以下限制：

1. 导入 JSON 文件时，需要使用 import attributes：

   import pkgJson from './package.json' with { type: 'json' }; // ✅ 正确
   import pkgJson from './package.json'; // ❌ 错误

2. 导入 TypeScript 文件时，需要包含 .ts 扩展名：

   import baseConfig from './rslib.base.config.ts'; // ✅ 正确
   import baseConfig from './rslib.base.config'; // ❌ 错误

详见 Node.js - Running TypeScript Natively。

#使用环境变量

在配置文件中，你可以使用 Node.js 环境变量，来动态写入不同的配置：

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',
    },
  },
});

#配置 Rsbuild

Rslib 允许你使用绝大部分的 Rsbuild 配置。目前不支持使用 environments 配置，因为该字段会在 Rslib 内部生成。

• 参考 Rsbuild 配置 了解常用的 Rsbuild 配置。
• 参考 Rsbuild 文档 了解所有 Rsbuild 配置。

#配置 Rspack

Rslib 基于 Rsbuild 构建，Rsbuild 支持直接修改 Rspack 配置对象，也支持通过 rspack-chain 修改 Rsbuild 内置的 Rspack 配置。这意味着你可以在 Rslib 项目中配置 Rspack 相关配置。

详情请参考 配置 Rspack。

#调试模式

你可以在执行构建时添加 DEBUG=rslib 环境变量来开启 Rslib 的调试模式。

DEBUG=rslib pnpm build

在调试模式下，Rslib 会输出一些额外的日志信息，并将内部经过 Rslib 处理最终生成的 Rsbuild 配置和 Rspack 配置写入到产物目录下，便于开发者查看和调试。

以下是一个例子，这个库设置了 CJS 和 ESM 两种输出格式：

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

• 打开生成的 /dist/.rsbuild/rsbuild.config.esm.mjs 文件，即可查看 Rsbuild 配置的完整内容。
• 打开生成的 /dist/.rsbuild/rspack.config.esm.mjs 文件，即可查看 Rspack 配置的完整内容。
• 打开生成的 /dist/.rsbuild/rslib.config.mjs 文件，即可查看 Rslib 配置的完整内容。