使用Typescript编写和发布npm包

本文参照 Chidume Nnamdi 的「How to Create and Publish an NPM module in TypeScript」博客,结合自身实践总结而成。
原文地址:https://codeburst.io/https-chidume-nnamdi-com-npm-module-in-typescript-12b3b22f0724

Step 1 初始化 Git 环境

  1. 在Github上创建一个远程仓库
  2. 下载到本地。
git clone https://github.com/youthcity/ts-hi.git

Step 2 初始化 NPM 包

npm init  # 或者使用, npm init -y 跳过所有提问

根据提示,填写相应信息,得到 package.json文件

# package.json

{
  "name": "ts-hi",
  "version": "0.0.1",
  "description": "create npm package with typescript",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/youthcity/ts-hi.git"
  },
  "keywords": [
    "typescript"
  ],
  "author": "youthcity",
  "license": "ISC",
  "bugs": {
    "url": "https://github.com/youthcity/ts-hi/issues"
  },
  "homepage": "https://github.com/youthcity/ts-hi#readme"
}

Step 3 安装依赖

安装 Typescript

# 使用 npm 安装
npm i typescript -D

# 或使用 yarn 进行安装
yarn add typescript -D

配置 tsconfig.json 文件

手动创建配置文件,文件如下

{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "declaration": true,
    "outDir": "./dist",
    "strict": true
  }
}

使用命令行创建。

# 需要全局安装 typescript包
npm i typescript -D
tsc --init 

# 使用当前项目中的 typescript
./node_modules/.bin/tsc --init

配置成的文件如下:

{
  "compilerOptions": {
    "target": "es5", // 指定ECMAScript目标版本
    "module": "commonjs", // 指定模块化类型
    "declaration": true, // 生成 `.d.ts` 文件
    "outDir": "./dist", // 编译后生成的文件目录
    "strict": true // 开启严格的类型检测
  }
}

Step 4 开始编码

mkdir lib # 在 ts-hi 根目录下,创建 lib 文件夹
touch index.ts

index.ts

# 非常简单的加法函数
export function add(a:number, b:number) : number {
  return a + b;
}

Step 5 编译

将编译命令添加到 package.json 文件中

{
  "name": "ts-hi",
  "version": "0.0.1",
  "description": "create npm package with typescript",
  "main": "index.js",
  "scripts": {
    "build": "tsc" # 增加 ts 编译命令
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/youthcity/ts-hi.git"
  },
  "keywords": [
    "typescript"
  ],
  "author": "youthcity",
  "license": "ISC",
  "bugs": {
    "url": "https://github.com/youthcity/ts-hi/issues"
  },
  "homepage": "https://github.com/youthcity/ts-hi#readme",
  "devDependencies": {
    "typescript": "^3.0.3"
  }
}

运行命令,执行编译

npm run build

编译完成后,我们可以看到目录下出现了 dist目录,在该目录下生成了两个文件,一个包含代码逻辑的 JS 文件,一个包含类型定义的 interface文件。

tsc 编译后生成的文件

Step 6 编写测试

1)安装测试框架和断言库

npm i mocha -D
npm i chai -D

2)创建测试文件目录和文件

# 根目录下
mkdir test && touch test/test.js

test.js

'use strict';
const expect = require('chai').expect;
const add = require('../dist/index').add;

describe('ts-hi function test', () => {
  it('should return 2', () => {
    const result = add(1, 1);
    expect(result).to.equal(2);
  });
});

Step 7 运行测试

添加测试脚本

  "scripts": {
    "build": "tsc",
    "test": "mocha --reporter spec"
  },

运行测试脚本

npm run test
测试结果

Step 8 添加 README

touch README.md

# 编写文档介绍...

Step 9 提交 和 推送远端

touch .gitignore // 创建 .gitignore 文件,并添加 node_modules/ 避免将node_modules 添加到版本控制中
git add . 
git commit -m “Initial release”
git tag v0.1.0  # 修改一下 package.json中的版本号为 0.1.0
git push origin master --tags

Step 10 发布

在发布代码之前,需要将一些没有必要的文件或目录从安装文件中排出。例如,lib文家目录。创建 .npmignore 文件。

.npmignore

# 排除 lib文件
lib/

登录 npm,并发布包

# 登录 npm, 若无账号,请在https://www.npmjs.com/ 注册账号
npm adduser
Username: youthcity
Password:
Email: (this IS public) 填写邮箱
Logged in as youthcity on https://registry.npmjs.org/.

# 发布包
npm publish

查看发布后的包: https://www.npmjs.com/package/ts-hi

Step 11 添加 CI(持续集成)

1)登录 Travis CI
2)点击 “Sign in with Github”
3)勾选需要持续集成的项目,本例为 ts-hi

travis 项目面板

4)在项目添加 travis 的配置文件
.travis.yml

language : node_js
node_js :
 - stable
install:
 - npm install
script:
 - npm test

5)将配置推送到 Github 的远程仓库。查看 travis 构建状态。


ts-hi 构建状态

其他功能

添加 Travis 构建徽章到 README

  1. 登录Travis并访问项目页面
  2. 获取徽章图片代码


    徽章代码

    获取代码
  3. 将代码粘贴到 README 中 (若需要多个 badge 并排展示,徽章代码之间,不要空行)
  4. git commit -m 'doc(README): add travis badge' && git push origin master

查看项目首页即可。例如,https://github.com/youthcity/ts-hi

添加代码覆盖率

  1. 使用 github 账号登录 coveralls,勾选需要执行代码覆盖率检查的仓库
  2. 在项目中,添加开发依赖
npm i istanbul -D
npm i coveralls -D
  1. 在 package.json 的配置文件中,添加脚本
"cover": "istanbul cover node_modules/mocha/bin/_mocha test/*.js - - -R spec"

添加后 package.json

  "scripts": {
    "build": "tsc",
    "test": "mocha --reporter spec",
    "cover": "istanbul cover node_modules/mocha/bin/_mocha test/*.js - - -R spec"
  },
  1. 修改 .travis.yml 文件
language : node_js
node_js :
 - stable
install:
 - npm install
script:  
 - npm run cover
 # Send coverage data to Coveralls
after_script: "cat coverage/lcov.info | node_modules/coveralls/bin/coveralls.js"
  1. 运行命令
npm run cover
  1. commit 和 推送代码到 github 仓库

登录 Coveralls ,检查是否执行顺利。

Coveralls / ts-hi

  1. 获取 Badge


    获取 Badge

如何快速生成 .gitignore

  1. 访问 https://www.gitignore.io/
  2. 选择项目环境。以本环境为例,输入 node、macOS、vscode(会自动提示为,VisualStudioCode)。
  3. 点击 Create,获取 .gitignore 文件

总结

通过使用 Typescript 编写 NPM 包,实践了很多以前遇到过但未使用过的技术。例如,Travis 的持续集成、 mochachai 编写测试、coveralls 代码覆盖、如何添加 badge 等。

参考资料

最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 206,839评论 6 482
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 88,543评论 2 382
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 153,116评论 0 344
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 55,371评论 1 279
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 64,384评论 5 374
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 49,111评论 1 285
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 38,416评论 3 400
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 37,053评论 0 259
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 43,558评论 1 300
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 36,007评论 2 325
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 38,117评论 1 334
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 33,756评论 4 324
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 39,324评论 3 307
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 30,315评论 0 19
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 31,539评论 1 262
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 45,578评论 2 355
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 42,877评论 2 345

推荐阅读更多精彩内容