lib.dts

  • 类型:
type Dts =
  | {
      bundle?: boolean | { bundledPackages?: string[] };
      distPath?: string;
      build?: boolean;
      abortOnError?: boolean;
      autoExtension?: boolean;
    }
  | boolean;
  • 默认值: undefined

配置 TypeScript 声明文件的生成。

布尔类型

类型声明文件生成是一个可选功能,你可以设置 dts: true 来启用 bundleless 类型 生成。

rslib.config.ts
export default {
  lib: [
    {
      format: 'esm',
      dts: true,
    },
  ],
};

如果你想要禁用类型声明文件生成,可以设置 dts: false 或者不指定 dts 选项。

rslib.config.ts
export default {
  lib: [
    {
      format: 'esm',
      dts: false,
    },
  ],
};

对象类型

如果你想要自定义类型声明文件的生成,可以将 dts 选项设置为一个对象。

dts.bundle

  • 类型: boolean | { bundledPackages?: string[] }
  • 默认值: false

是否打包类型声明文件。

如果你想要 bundle 类型,你需要:

  1. 安装 @microsoft/api-extractor 作为开发依赖,它是用于打包类型声明文件的底层工具。
npm
yarn
pnpm
bun
npm add @microsoft/api-extractor -D
  1. dts.bundle 设置为 true
rslib.config.ts
export default {
  lib: [
    {
      format: 'esm',
      dts: {
        bundle: true,
      },
    },
  ],
};

dts.bundle.bundledPackages

  • 类型: string[]

用于指定需要打包类型声明文件的依赖项,该配置将传递给 @microsoft/api-extractorbundledPackages 配置项。

默认情况下,Rslib 会根据以下配置确定需要外部化的依赖项,详见 处理第三方依赖

那些没有被外部化的直接依赖项(在 package.json 中声明)会被添加到 bundledPackages 中,这些包的类型声明文件将会被打包到最终的产物中。

当默认行为不能满足需求时,可以通过 dts.bundle.bundledPackages 显式指定需要打包的依赖项。设置该配置后,将完全覆盖上述默认行为。

该配置通常用于打包传递依赖项(即直接依赖的依赖)。假设项目直接依赖 foo,而 foo 又依赖 bar,如果需要同时打包 foobar 的类型声明文件,可以如下配置:

rslib.config.ts
export default {
  lib: [
    {
      format: 'esm',
      dts: {
        bundle: {
          bundledPackages: ['foo', 'bar'],
        },
      },
    },
  ],
};
NOTE

bundledPackages 可以使用 minimatch 语法配置 glob 表达式,但仅会匹配 package.json 中已声明的直接依赖项。

dts.distPath

  • 类型: string

类型声明文件的输出目录。

默认值

默认值按照以下优先级确定:

  1. 当前 lib 配置中的 dts.distPath 值。
  2. tsconfig.json 文件中的 declarationDir 值。
  3. 当前 lib 配置中的 output.distPath.root 值。

示例

rslib.config.ts
export default {
  lib: [
    {
      format: 'esm',
      dts: {
        distPath: './dist-types',
      },
    },
  ],
};

dts.build

  • 类型: boolean
  • 默认值: false

是否在生成类型声明文件时构建项目的 references。这相当于在 tsc 命令中使用 --build 标志。更多详细信息请参考 项目引用

NOTE

当启用此选项时,你必须在 tsconfig.json 中显式设置 declarationDiroutDir 以满足构建要求。

dts.abortOnError

  • 类型: boolean
  • 默认值: true

当类型声明文件生成过程中出现错误时,是否中止构建过程。

默认情况下,类型错误会导致构建失败。

abortOnError 设置为 false 时(如下所示),即使代码中存在类型问题,构建仍然会成功。

rslib.config.ts
export default {
  lib: [
    {
      format: 'esm',
      dts: {
        abortOnError: false,
      },
    },
  ],
};
WARNING

当禁用该配置时,无法保证类型文件会被正确生成。

dts.autoExtension

  • 类型: boolean
  • 默认值: false

是否根据 format 选项自动设置类型声明文件扩展名。

默认扩展名

dts.autoExtensionfalse 时,类型声明文件扩展名默认为 .d.ts

dts.autoExtension 设置为 true 时,类型声明文件扩展名将会是:

  • package.json 中设置 type: module 时,esm 格式使用 .d.tscjs 格式使用 .d.cts

  • package.json 中设置 type: commonjs 或没有 type 字段时,cjs 格式使用 .d.tsesm 格式使用 .d.mts

NOTE

这遵循与 lib.autoExtension 相同的逻辑,但默认值不同,因为类型声明文件扩展名可能会在不同的模块解析策略中造成一些问题。