用TypeScript编写发布函数库

做者简介 zqlu 蚂蚁金服·数据体验技术团队

为何使用TypeScript编写函数库

TypeScript做为一种有类型定义的JavaScript超集语言，用来写函数库除了给本身开发者本身带来如开发效率提高、静态检查等好处外，对库的使用方也能带来一下好处：

• 对于直接使用JavaScript的使用者，经过TypeScript的编译过程，能够生成直接使用的JavaScript代码，如ES5版本的JavaScript代码，对使用者的使用没有影响
• 对于使用TypeScript的开发者，经过TypeScript编译生成的定义文件，能极大提高使用者的使用体验

函数库的编译控制

代码库在发布以后，使用者可能指望能以各类方式来使用库，如直接在浏览器中加载使用、经过NodeJs的CommonJS模块方式来引用代码库、或者直接经过ES6的module方式来引用。

在使用TypeScript编写代码库后，开发者能够不用关心代码库使用者的饮用方式，而直接使用TypeScript的模块机制来模块化编写代码库；而是在经过TypeScript的编译过程来生成

下面分别介绍以上几种不一样使用情景下的编译过程。

CommonJS模块化代码的生成

目前前端开发库绝大部分都会发布到npm上，npm做为NodeJs的包管理器，提供CommonJs的模块化代码是很是有必要的。

经过tsconfig.json来配置CommonJS模块代码的生成：

{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "moduleResolution": "node",
    "outDir": "dist/cmjs",
    "rootDir": "./src",
    "declaration": true,
    "sourceMap": true,
    "lib": ["dom", "es6"]
  }
}
复制代码

经过以上配置， "module": "commonjs" 来申明编译生成目标代码模块为commonjs，生成目标代码目录为："outDir": "dist/cmjs"。

同时在package.json中，经过main字段来申明CommonJS的入口文件：

{
  	"name": "myLib",
  	"version": "0.1.0",
    "main": "dist/cmjs/index.js",
}
复制代码

ES6模块代码的生成

随着ES6标准的流行，以及各类打包工具对ES6模块的原生支持，如webpack的resolve.mainFields配置，提供ES6模块代码可以让使用者享受ES6模块的一些特性。

同CommonJS同样，也能够经过配置tsconfig.json的方式来生成ES6模块代码，但通常在tsconfig.json中使用commonjs做为默认配置，因此能够在package.json中经过添加script来经过TypeScript编译器命令行参数来编译生成ES6模块代码：

{
    "name": "myLib",
  	"script": {
        "build:cmjs": "tsc -P tsconfig.json",
      	"build:es6": "tsc -P tsconfig.json --module ES6 --outDir dist/es6",
      	"build": "npm run build:cmjs; npm run build:es6"
    }
}
复制代码

其中 build:cmsj 编译生成CommonJS模块目标代码，build:es6编译生成ES6模块目标代码。对于ES6模块的代码，经过在package.json中的module字段来申明ES6模块代码的入口文件，以便可以识别ES6模块的模块加载器使用：

{
  	"name": "myLib",
  	"version": "0.1.0",
    "main": "dist/cmjs/index.js",
 	"module": "dist/es6/index.js",
}
复制代码

可以直接给浏览器使用的代码生成

生成可以直接给浏览器使用的代码，可以方便使用者，不须要使用包管理器，直接在html文件中引用。如React，能够直接在HTML文件中引入dist/react.js单独文件。对此，须要对模块化分布的代码按依赖合并大包，因此使用打包工具如webpack彻底能够作到，这里不仔细介绍。

另外，还能够能够借助Browserify工具来将上述编译生成的CommonJS模块化代码总体打包成可供浏览器直接使用的代码。一样，经过简单的添加package.json的script来完成：

{
    "name": "myLib",
  	"script": {
        "build:cmjs": "tsc -P tsconfig.json",
      	"build:es6": "tsc -P tsconfig.json --module ES6 --outDir dist/es6",
      	"build:web": "browserify dist/cmjs/index.js --standalone myLib -o dist/web/bundle.js",
      	"build": "npm run build:cmjs; npm run build:es6"
    }
}
复制代码

版本与发布

语义化版本

语义化版本使用如：主版本号.次版本号.修订号 的版本格式，有详细严格的定义文档。遵循语义化版本号规则有利于使用者理解代码库的升级修改，共同遵循语义化版本号能使开发者和使用者共同获益。

此外，文档中还提到了一些常见的问题，如：

• 在函数库开发阶段，若是控制版本号？推荐是从0.1.0版本开始
• 如何判断发布1.0.0的时机？软件被应用在正式环境；有固定的API被使用者依赖；存在向下兼容问题的时候
• 对于公共API，即便是最小但向下不兼容的改变都须要产生新的主版本号，岂不是很快就到了如42.0.0版？这是开发的责任感和前瞻性的问题，为何有这么多不兼容更改：）

发布版本

在TypeScript编写函数库后，须要更新版本时候，推荐使用npm version命令来更新版本号，如：

• 更新修订号：npm version patch

• 更新此版本号：npm version minor

• 更新主版本号：npm version major

执行上述命令，会增长相应的版本号保存到package.json的version字段中。在使用git作源码版本控制的时候，还能够添加-m参数来自动成来提供一条版本更新commit记录和tag记录，如运行npm version patch -m "update version %s"除了更新package.json中的version字段外，还会自动生成一条commit记录，commit message中的%m 会被替换成新生成的版本号，此外还有自定生成tag记录。

对Typescript感兴趣的同窗能够关注专栏或者发送简历至'lingdao.lzq####alibaba-inc.com'.replace('####', '@')，欢迎有志之士加入~

原文地址：github.com/ProtoTeam/b…