#类型生成

本章介绍什么是 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 的类型生成流程可以分为两步：

1. 类型生成，即生成 bundleless 类型。支持以下三种方式：
   • TypeScript Compiler API
   • tsgo
   • isolatedDeclarations
2. 类型打包，即生成 bundle 类型（可选）。开启 dts.bundle 时会将生成的类型声明文件通过 API Extractor 进行打包。

#生成 bundleless 类型

类型声明文件可以通过以下三种方式生成：

#TypeScript compiler API

默认行为，与执行 tsc 的效果基本相同，会生成类型声明文件并执行类型检查，但是速度相对较慢。

export default {
  lib: [
    {
      dts: true; 
      // 或者
      dts: {
        bundle: false;
      }
    },
  ],
};

#tsgo

使用 TypeScript Go 生成类型声明文件，可以在保留类型检查的同时，显著加快类型生成的速度。

安装 TypeScript 7 或更高版本后，Rslib 会自动开启 dts.tsgo。

npm add typescript@rc -D

yarn add typescript@rc -D

pnpm add typescript@rc -D

bun add typescript@rc -D

deno add npm:typescript@rc -D

你也可以安装 @typescript/native-preview，并在 Rslib 配置文件中开启 dts.tsgo。

npm add @typescript/native-preview -D

yarn add @typescript/native-preview -D

pnpm add @typescript/native-preview -D

bun add @typescript/native-preview -D

deno add npm:@typescript/native-preview -D

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

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

{
  "typescript.experimental.useTsgo": true
}

#isolatedDeclarations

开启 dts.isolated 会使用 Rspack 内置的 SWC fast_dts 能力生成类型声明文件，这种方式速度最快，但不会执行类型检查，并且仅会输出构建依赖图中包含模块的类型声明文件。

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

启用该选项时，建议同时在 tsconfig.json 中开启 isolatedDeclarations：

{
  "compilerOptions": {
    "isolatedDeclarations": true
  }
}

#生成 bundle 类型

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

npm add @microsoft/api-extractor -D

yarn add @microsoft/api-extractor -D

pnpm add @microsoft/api-extractor -D

bun add @microsoft/api-extractor -D

deno add npm:@microsoft/api-extractor -D

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

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

#注意事项

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

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

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

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

#相关配置