#配置 Rslib

Rslib 的配置是基于 Rsbuild 扩展的，这意味着你可以使用 Rsbuild 的所有配置，以及 Rslib 特有的 lib 配置。

#配置结构

Rslib 提供了 lib 选项来配置库产物，它是一个数组，每个对象用于描述一种输出格式。

例如，输出 ESM 和 CJS 两种格式的产物，并使用 es2021 语法：

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

#公共的 Rsbuild 配置

在 lib 字段外部，你可以设置公共的 Rsbuild 配置，这些配置将被 lib 内的每个配置对象继承。

例如，设置 Rsbuild 的 output.target 为 web，这会影响所有 lib 配置对象的输出：

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

#单独的 Rsbuild 配置

在 lib 字段内部，你可以为每种输出格式设置单独的 Rsbuild 配置，这些配置将覆盖外部的公共 Rsbuild 配置。

例如，单独设置 ESM 产物的 output.target 为 web：

export default {
  lib: [
    // ESM 产物的 target 为 `web`
    {
      format: 'esm',
      output: {
        target: 'web',
      },
    },
    // CJS 产物继承了公共配置，target 为 `node`
    {
      format: 'cjs',
    },
  ],
  output: {
    target: 'node',
  },
};

Rslib 会在内部生成 Rsbuild 的 environments 配置，可以运行 rslib inspect 命令来查看最终生成的配置。

你也可以在 配置概览 页面查看所有配置的详细介绍。

#配置文件

当你使用 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 build --config rslib.prod.config.mjs"
  }
}

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

rslib build -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 build --config-loader native
  
  # Node.js v22.6.0 - v22.17.1
  # 需要设置 --experimental-strip-types
  NODE_OPTIONS="--experimental-strip-types" npx rslib build --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=rsbuild 环境变量来开启 Rslib 的调试模式。

DEBUG=rsbuild 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

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