使用Rollup实现生成TypeScript类型

背景

已有项目的.d.ts文件是手动维护的, 虽然比较多老旧的js库的类型定义也是手动维护, 但是我们是直接使用ts来开发我们的库的, 所以需要一种自动化和现代的方案来生成我们库的定义文件

• tsc --declaration能生成.d.ts文件, 但是这些文件是分散的, 使用起来并不友好
• 使用dts-generator或dts-bundle将所有的.d.ts文件打包成一个, 但是都不是官方方案, 而且比较老旧, 处于不活跃状态
• 研究过很多项目后, 发现了一个神器: api-extractor, 微软官方出品维护, 可以合并.d.ts文件, 还能做到lint的效果, 检查代码中的错误

使用

使用api-extractor的相关资料并不多, 所以最后决定直接参考官方文档来实现, 按文档说明流程非常简单

flowchart TD A(ts源码) --> |tsc|B(多文件.d.ts) B --> |api-extractor|C(单文件.d.ts)

配置api-extractor

其中messages字段是一些错误提示忽略的配置, 类似于eslint的rule, 有些想忽略的warning就可以在这里配置以后保证lint检查是成功的

// api-extractor.json
{
  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
  "mainEntryPointFilePath": "dist/types/index.d.ts",
  "bundledPackages": [],
  "apiReport": {
    "enabled": false,
    "reportFolder": "dist/lib/"
  },
  "docModel": {
    "enabled": true
  },
  "dtsRollup": {
    "enabled": true,
    "untrimmedFilePath": "dist/lib.es5.d.ts"
  },
  "messages": {
    "extractorMessageReporting": {
      "ae-missing-release-tag": {
        "logLevel": "none"
      }
    }
  }
}

编译脚本

在package.json里加上相关命令, 就可以直接生成.d.ts文件了

{
  "typings": "dist/types/index.d.ts",
  "scripts": {
    "build": "tsc --module commonjs && api-extractor run && rollup -c rollup.config.ts && typedoc --out docs --theme minimal src",
    "api": "tsc --module commonjs && api-extractor run"
  }
}

使用

生成完成后, 可以看到dist目录下的结构就非常清晰了, 只剩下五份文件:

• lib.es5.js
• lib.es5.js.map
• lib.umd.js
• lib.umd.js.map
• lib.es5.d.ts

然后就可以在demo的react里很舒服的直接使用ts类型了, 和使用其他库的效果一样.

import LibSDK, { SDKOptions } from '../dist/lib.es5';