#lib.dts

• 类型：

type Dts =
  | {
      bundle?: boolean | { bundledPackages?: string[] };
      distPath?: string;
      build?: boolean;
      abortOnError?: boolean;
      autoExtension?: boolean;
      alias?: Record<string, string>;
      tsgo?: boolean;
    }
  | boolean;

• 默认值： undefined

配置 TypeScript 声明文件的生成。

#布尔类型

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

export default {
  lib: [
    {
      format: 'esm',
      dts: true,
    },
  ],
};

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

export default {
  lib: [
    {
      format: 'esm',
      dts: false,
    },
  ],
};

#对象类型

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

#dts.bundle

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

是否打包类型声明文件。

如果你想要 bundle 类型，你需要：

1. 安装 @microsoft/api-extractor 作为开发依赖，它是用于打包类型声明文件的底层工具。

npm add @microsoft/api-extractor -D

2. 将 dts.bundle 设置为 true。

export default {
  lib: [
    {
      format: 'esm',
      dts: {
        bundle: true,
      },
    },
  ],
};

#dts.bundle.bundledPackages

• 类型： string[]

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

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

• autoExternal 配置
• output.externals 配置

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

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

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

export default {
  lib: [
    {
      format: 'esm',
      dts: {
        bundle: {
          bundledPackages: ['foo', 'bar'],
        },
      },
    },
  ],
};

#dts.distPath

• 类型： string

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

#默认值

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

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

#示例

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

#dts.build

• 类型： boolean
• 默认值： false

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

在配置了 project references 但被引用的项目尚未单独构建时（例如在 monorepo 中直接引用其他项目的源代码，但项目中缺少对应的类型声明文件），需要开启此选项，以确保能够正确生成依赖项目的类型声明，从而保障类型系统的完整性。

#dts.abortOnError

• 类型： boolean
• 默认值： true

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

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

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

export default {
  lib: [
    {
      format: 'esm',
      dts: {
        abortOnError: false,
      },
    },
  ],
};

#dts.autoExtension

• 类型： boolean
• 默认值： false

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

#默认扩展名

当 dts.autoExtension 为 false 时，类型声明文件扩展名默认为 .d.ts。

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

• 当 package.json 中设置 type: module 时，esm 格式使用 .d.ts，cjs 格式使用 .d.cts。

• 当 package.json 中设置 type: commonjs 或没有 type 字段时，cjs 格式使用 .d.ts，esm 格式使用 .d.mts。

#dts.alias

• 类型： Record<string, string>
• 默认值： {}

用于配置类型声明文件的路径别名。

dts.alias 会与 tsconfig.json 中配置的 compilerOptions.paths 合并，且 dts.alias 具有更高的优先级。

大部分情况下，你不需要使用 dts.alias，但当你需要在类型声明文件中使用路径别名却不希望影响 JavaScript 产物时，可以考虑使用它。比如，将 foo 的类型声明文件指向 ./compiled/foo。

export default {
  lib: [
    {
      dts: {
        alias: {
          foo: './compiled/foo',
        },
      },
    },
  ],
};

#dts.tsgo

• 类型： boolean
• 默认值： false

是否使用 tsgo 生成类型声明文件。tsgo 可以提供更快的类型声明文件生成速度，尤其是对于大型项目。

启用该选项，你需要：

1. 安装 @typescript/native-preview 作为开发依赖。

npm add @typescript/native-preview -D

2. 在 Rslib 配置文件中设置：

export default {
  lib: [
    {
      dts: {
        tsgo: true,
      },
    },
  ],
};

3. 为了保证本地开发的一致性，你需要安装对应的 VS Code 预览版扩展，并在 VS Code 设置中添加如下配置：

{
  "typescript.experimental.useTsgo": true
}