类型生成#

本章介绍什么是 TypeScript 类型声明文件，以及如何在 Rslib 中生成类型声明文件。

什么是类型声明文件#

TypeScript 类型声明文件提供 JavaScript 代码的类型信息。类型声明文件通常具有 .d.ts 扩展名。它们允许 TypeScript 编译器理解 JavaScript 代码的类型结构，从而实现以下功能：

1. 类型检查: 为 JavaScript 代码提供类型信息，帮助开发人员在编译时捕获潜在的类型错误。
2. 代码补全: 增强代码编辑器功能，例如自动完成和代码导航。
3. 文档生成: 生成 JavaScript 代码文档，提供更好的开发体验。
4. IDE 支持: 改善 Visual Studio Code、WebStorm 等 IDE 中的开发者体验。
5. 库消费: 让其他使用者更容易使用和理解该库。

什么是 bundle 类型和 bundleless 类型#

Bundle 类型#

Bundle 类型将多个 TypeScript 声明文件打包到一个声明文件中。

• 优势:

  • 简化管理: 简化类型文件的管理和引用。
  • 容易分发: 减少用户使用库时需要处理的文件数量。

• 劣势:

  • 生成复杂: 在大型项目中，生成和维护单个 bundle 文件可能会变得复杂。
  • 调试困难: 调试类型问题可能不像各个文件单独输出那样直观。

Bundleless 类型#

Bundleless 类型为库中的每个模块生成单独的声明文件，就像 tsc 一样。

• 优势:

  • 模块化: 每个模块都有自己的类型定义，使维护和调试更容易。
  • 灵活: 适合大型项目，避免单个文件的复杂性。

• 劣势:

  • 多文件: 用户在使用该库时可能需要处理多个声明文件。
  • 管理复杂: 可能需要额外的配置才能正确引用所有文件。

如何在 Rslib 中生成类型声明文件#

Rslib 默认使用 TypeScript Compiler API 生成 bundleless 类型，用 API Extractor 生成 bundle 类型。

如果你想生成 bundleless 类型，可以：

• 设置 dts: true 或者 dts: { bundle: false } 在 Rslib 配置文件。

如果你想生成 bundle 类型，可以：

1. 安装 @microsoft/api-extractor 作为 devDependencies, 这是用于打包类型声明文件的底层工具。

npm add @microsoft/api-extractor -D

2. 在 Rslib 配置文件中设置 dts: { bundle: true }。

需要注意的是，Rslib 在生成类型声明文件的过程中，默认会强制设置 tsconfig.json 中的一些配置项以保证 TypeScript Compiler API 能够仅生成类型声明文件。

{
  "compilerOptions": {
    "noEmit": false,
    "declaration": true,
    "emitDeclarationOnly": true
  }
}

最终类型声明文件输出目录的优先级从高到低为：

• dts.distPath 配置项
• tsconfig.json 中的 declarationDir 配置项
• output.distPath.root 配置项