#类型生成

本章介绍什么是 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 API
   • TypeScript 可执行文件
   • isolatedDeclarations
2. 类型打包，即生成 bundle 类型（可选）。开启 dts.bundle 时会将生成的类型声明文件通过 API Extractor 进行打包。

#生成 bundleless 类型

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

#TypeScript API

TypeScript 5/6 使用 TypeScript Compiler API，与执行 tsc 的效果基本相同，会生成类型声明文件并执行类型检查，但速度相对较慢。

TypeScript 7.1 及以上版本使用 native TypeScript 的 JavaScript API，生成速度更快。

在 rslib.config.ts 中开启 dts 即可生成类型声明文件：

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

安装 TypeScript 7 及以上版本，可以使用 native TypeScript 加快类型声明生成。

npm add typescript@latest -D

yarn add typescript@latest -D

pnpm add typescript@latest -D

bun add typescript@latest -D

deno add npm:typescript@latest -D

在 VS Code 中使用 native TypeScript，可以安装 TypeScript 7 扩展，并启用以下设置：

{
  "js/ts.experimental.useTsgo": true
}

#TypeScript 可执行文件

使用 TypeScript 7.0 时，Rslib 通过 native TypeScript 可执行文件生成类型声明文件。

#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 配置文件中将 dts.bundle 设置为 true：

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

{
  "compilerOptions": {
    "types": ["node"]
  }
}

#注意事项

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

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

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

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

#Content mappers

Rslib 支持使用 TypeScript 7.1 中新增的 Content Mappers 生成类型声明。

安装 content mapper 后，在 tsconfig.json 中注册它处理的文件扩展名。例如，假设已安装名为 example-css-modules-mapper 的 CSS Modules mapper（仅为示例包名）：

{
  "contentMappers": [
    {
      "package": "example-css-modules-mapper",
      "extensions": [".module.css"]
    }
  ]
}

生成类型声明时，Rslib 会自动加载该 mapper，根据 CSS Modules 的类名生成类型。

#相关配置