配置 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 的 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

使用环境变量#

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

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

配置 Rsbuild#

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

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

配置 Rspack#

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

详情请参考 配置 Rspack。

调试配置#

在执行构建时，你可以通过添加 DEBUG=rsbuild 环境变量来启用 Rslib 的调试模式，它会在 Rslib 处理后显示最终的 Rsbuild 和 Rspack 配置。

DEBUG=rsbuild pnpm build

在调试模式下，Rslib 会将 Rsbuild 和 Rspack 配置写入到 dist 目录下，方便开发者查看和调试。

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

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