用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…