在2018年如何优雅的开发一个typescript语言的npm包?

很多时候,我们可能想要用 typescript 语言来创建一些模块,并提交到 npm 供别人使用,

那么在 2018 年,如果我想要初始化这样的一个模块,我需要做哪些步骤呢?

答案是:创建一个优雅的,对开发者友好的模块,至少需要以下 15 个步骤

  1. 初始化文件夹,初始化 git 仓库,初始化 npm,初始化 tsc
  2. 修改 tsconfig.js 配置
  3. 添加 npm 脚本
  4. 添加 tslint 校验代码规则以及 editorconfig,prettier 统一代码风格
  5. 设置 git 提交的校验钩子
  6. 开始编写代码
  7. watch 模式开发
  8. 忽略 ts 编译生成的文件夹
  9. 添加单元测试
  10. 写一个单元测试示例
  11. 设置一些有用的 npm 脚本
  12. 完善 package.json 的描述信息
  13. 提交代码到 git 仓库
  14. 发布包到 npm

本篇文章里,我会列出每个步骤的详细说明。

实际开发中,如果每个包都去走一遍这些步骤,步骤好像确实有点多。所以如果你需要实际创建项目的时候,你可以选择 clone 我提供的样板项目 来开始一个新的 ts 模块的开发,主要步骤如下:

git clone https://github.com/xiaomingplus/npm-typescript-boilerplate.git your-project-name
cd your-project-name
# 安装依赖
npm i
# 开始开发
npm start
# 修改 package.json 里面的项目名和简介
# 修改 README.md 文件内容
# 修改 远程仓库的地址
git remote set-url origin your-git-url

下面就是常规步骤了,学习目的的话,建议按照下面的步骤全部跑一遍:

1. 初始化文件夹,初始化 npm,初始化 tsc

mkdir project-name
cd project-name
# 初始化git项目
git init
# 添加gitignore文件
touch .gitignore
# 复制这个地址的ignore内容到.gitignore <https://github.com/github/gitignore/blob/master/Node.gitignore>

# 添加readme文件
echo "# My Awesome Typescript Project" >> README.md
# 安装typescript
npm install --save-dev typescript
# 初始化npm包
npm init --y
# 初始化tsconfig
tsc --init

2. 修改 tsconfig.js 配置

修改以下默认配置:

{
    "compilerOptions": {
        "declaration": true,
        "outDir": "./lib",
     },
    "include": ["src"],
    "exclude": ["node_modules", "**/__tests__/*"]
}

最终的 tsconfig 配置如下:

{
    "compilerOptions": {
        "target": "es5",
        "module": "commonjs",
        "declaration": true,
        "strict": true,
        "outDir": "./lib",
        "esModuleInterop": true
    },
    "include": ["src"],
    "exclude": ["node_modules", "**/__tests__/*"]
}

3. 添加 npm 脚本

在 package.json 里编辑 scripts 字段:

{
  "scripts": {
    "start": "tsc -w",
    "build": "tsc"
  }
}

4. 添加 tslint 校验代码规则以及 editorconfig,prettier 统一代码风格

npm install --save-dev prettier tslint tslint-config-prettier

新建tslint.json文件

{
  "extends": ["tslint:recommended", "tslint-config-prettier"],
  "rules": {
    "no-console": false,
    "object-literal-sort-keys": false,
    "member-access": false,
    "ordered-imports": false
  },
  "linterOptions": {
    "exclude": ["**/*.json", "node_modules"]
  }
}

新建 .prettierrc 文件

{
  "trailingComma": "all",
  "tabWidth": 4,
  "semi": false,
  "singleQuote": true,
  "endOfLine": "lf",
  "printWidth": 120,
  "overrides": [
    {
      "files": ["*.md", "*.json", "*.yml", "*.yaml"],
      "options": {
        "tabWidth": 2
      }
    }
  ]
}

新建 .editorconfig

# EditorConfig is awesome: https://EditorConfig.org

# top-most EditorConfig file
root = true

# Unix-style newlines with a newline ending every file
[*]
end_of_line = lf
insert_final_newline = true
charset = utf-8
indent_style = space
indent_size = 4

[{*.json,*.md,*.yml,*.*rc}]
indent_style = space
indent_size = 2

添加一个便捷的 scripts 脚本:

{
  "scripts": {
    "format": "prettier --write \"src/**/*.ts\" \"src/**/*.js\"",
    "lint": "tslint -p tsconfig.json"
  }
}

5. 设置 git 提交的校验钩子

设置 git 提交的钩子校验规范

npm install --save-dev husky @commitlint/config-conventional @commitlint/cli commitizen cz-conventional-changelog

新建 commitlint.config.js 文件

touch commitlint.config.js

写入:

module.exports = {
  extends: ["@commitlint/config-conventional"]
};

新建 .huskyrc 文件

touch .huskyrc

写入:

{
    "hooks": {
        "pre-commit": "npm run format && npm run lint && npm test",
        "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    }
}

新建配置文件:

touch .czrc

写入配置:

{ "path": "cz-conventional-changelog" }

package.json 新增 scripts 配置:

{
  "scripts": {
    "commit": "git-cz"
  }
}

6. 开始编写代码

cd project-name
mkdir src
cd src
touch index.ts

写下你的第一行 ts 代码:

export const Greeter = (name: string) => `Hello ${name}`;

7. watch 模式下开发

npm start

8. 忽略 ts 编译生成的文件夹

/lib文件夹添加到.gitignore

/lib

9. 添加单元测试

npm install --save-dev jest ts-jest @types/jest

创建 jestconfig.json文件:

{
  "transform": {
    "^.+\\.(t|j)sx?$": "ts-jest"
  },
  "testRegex": "(/__tests__/.*|(\\.|/)(test|spec))\\.(jsx?|tsx?)$",
  "moduleFileExtensions": ["ts", "tsx", "js", "jsx", "json", "node"]
}

修改 package.json 里的 scripts 下的 test :

{
  "scripts": {
    "test": "jest --config jestconfig.json"
  }
}

10. 写一个单元测试示例

src 文件夹下新建一个 __tests__的文件夹来存放测试用例文件,新建一个 Greeter.test.ts文件,写入:

import { Greeter } from "../index";
test("My Greeter", () => {
  expect(Greeter("Carl")).toBe("Hello Carl");
});

运行测试用例:

npm test

结果应该是通过的。

11. 设置一些有用的 npm 脚本

prepare: 发布前和用户安装前运行

prepublishOnly: 发布前运行

preversion: 新建一个版本前运行

version: 新建一个版本后运行

postversion: 新建版本后运行

{
  "scripts": {
    "prepare": "npm run build",
    "prepublishOnly": "npm test && npm run lint",
    "preversion": "npm run lint",
    "version": "npm run format && git add -A src",
    "postversion": "git push && git push --tags"
  }
}

12. 完善 package.json 的描述信息

name 完善包名,描述,包入口文件 main 字段,typescript 类型文件 types 字段定义

{
    "name": "project-name"
    "description": "A nice greeter",
    "main": "lib/index.js",
    "types": "lib/index.d.ts"
}

13. 完善文档信息

新建 doc 文件夹,在里面可以写一些模块详细的文档:

mkdir doc

完善 readme.md的信息,格式可以参考 这里

14. 提交代码到 git 仓库

发布之后就把代码提交到 git 仓库吧

git add .
git commit -m "feat: init"
# 关联到远程仓库不属于本教程的内容,就不写push了

15. 发布包到 npm

如果你还没注册 npm 的用户的话,需要先注册。

npm adduser

注册好之后就可以发布到 npm 了:

# 自动修改package.json文件版本号+1
npm version patch
npm publish

发布之后,你可以去 https://www.npmjs.com/ 上找到你的包

参考

Step by step: Building and publishing an NPM Typescript package.

原创声明,本文系作者授权云+社区发表,未经许可,不得转载。

如有侵权,请联系 yunjia_community@tencent.com 删除。

发表于

小明plus

1 篇文章3 人订阅

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏jmeter高手高高手

JMeter(十三)-代理服务器录制脚本

3:在Requests FIltering下添加排除模式,配置正则表达式。否则会录制出很多凌乱的请求。

2202
来自专栏大闲人柴毛毛

Linux文件的默认权限与查找命令详解

今天被csdn坑了!昨晚写了一夜的博客,保存到线上草稿了!可是今天打开博客,草稿箱里也找不到,发布的文章中也找不到!作为一家专门研讨技术的网站,居然还会在技术上...

43816
来自专栏xiaoheike

Elasticsearch Network Settings

Elasticsearch 缺省情况下是绑定 localhost。对于本地开发服务是足够的(如果你在相同机子上启动多个节点,它还可以形成一个集群),但是你需要配...

1482
来自专栏我和PYTHON有个约会

python-应用层-网络编程-FTP

前面描述的基于TCP/UDP协议的网络程序开发,主要是针对传输层协议的底层代码实现 在实际操作过程中,更多的情况是直接操作应用层的数据协议的网络程序开发,如文...

1183
来自专栏web编程技术分享

快速入门Http协议

3755
来自专栏做全栈攻城狮

零基础学.NET电脑编程-线程 进程 多线程讲解 程序员必备

这是学习电脑编程的第二部分,带领你一起开发电脑桌面应用程序的第三课。上一课链接:Winform零基础入门教程-实现音乐播放器的歌词显示功能

932
来自专栏zaking's

走近webpack(2)--css打包及压缩js

  前面的文章介绍了webpack的devServer以及多入口多出口文件的配置,咱们继续往下学。   在开始学习接下来的知识之前,我们先回顾一下,前文提到了w...

4908
来自专栏小勇DW3

亿级流量场景下,大型缓存架构的虚拟机环境搭建

静态模板是固定的 数据库中的数据全量喧嚷到模板中,下次请求来了直接返回,速度也很快;

1964
来自专栏云计算教程系列

【基础干货】Linux Shell基础教程

shell,也称为“命令行界面”或“CLI”,是与远程Linux服务器交互的主要方法。shell是一个丰富的界面,用于处理文件,管理系统和编写常见任务脚本。如果...

1374
来自专栏PHP技术大全

Grafana+prometheus+php 自动创建监控图

在grafana+ prometheus+php 监控系统实践文章当中已经实现了我们的第一个监控图表,现在我们有了一个新需求,需要对多个节点实现不同的监控,以及...

3033

扫码关注云+社区

领取腾讯云代金券