发布一个具有提示功能的npm包

---

title: 发布一个具有提示功能的npm包
date: 2018-01-06 22:04:08
tags:

---

2018年了, 前几天合肥下了一场大雪, 现在是小寒节气, 晚上写博客有点冷.

今天发布了一个 npm 包 @penggy/mysql , 在使用过程中, 发现 vscode 不能对其中的 api 提供智能提示. 于是查资料, 将其改造成自带提示的包. 这样在其他 vscode 项目里面 npm install 它之后, 就能 api 提示, 方便其他开发者使用.

使用 typescript 编写发布包代码

发布包代码使用 typescript 语言编写, typescript 编译器将 ts 文件编译成 js 文件的同时, 能够生成后缀为 d.ts 的类型声明文件, 这个文件便是 vscode 提示功能的关键. vscode 正是通过解析 *.d.ts 这种类型声明文件来支持提示功能.

开始一个 typescript 项目:

安装 typescript 编译器

npm i -g typescript

生成项目配置文件 tsconfig.json

tsc --init

tsconfig.json 内容如下:

{
  "compilerOptions": {
    "target": "ES6", 
    "module": "commonjs",                     
    "declaration": true
  }
}

其中 declaration true 表示将要生成 d.ts 类型声明文件, 我们要把这个文件介绍给 vscode , 好使它有针对我们这个库的提示功能.

编译 ts 到 js

在 vscode 里, 编译 ts 到 js 非常简单, 按住 Ctrl + Shift + B 可选仅编译一次, 或者开启监听模式(保存 ts 文件, 立即触发编译动作).

编译完成, 在 ts 文件同目录下, 生成对应的同名 .js 和 .d.ts 文件

在 package.json 中声明类型文件位置

package.json 文件中, 加入 types 字段如下:

{
  "name": "@penggy/mysql",
  "version": "1.0.6",
  "description": "Promise wrapper of mysql",
  "main": "./index.js",
  "types": "./index.d.ts",

types 也可以写成 typings, 效果相同, 官方参考

将 js 和 d.ts 文件包含到发布文件

ts 文件不需要发布到 npm 包, 但是编译生成的 js 和 d.ts 文件需要发布到 npm.

修改 package.json 如下:

{
  "name": "@penggy/mysql",
  "version": "1.0.6",
  "description": "Promise wrapper of mysql",
  "main": "./index.js",
  "types": "./index.d.ts",
  "scripts": {
    "test": "node test.js"
  },
  "files": [
    "index.js",
    "index.d.ts",
    "README.md"
  ],

files 字段指定工程目录下面哪些文件需要发布到 npm.

发布到 npm

npm publish

至此, 发布一个具有提示功能的 npm 包完成. 在其他项目中, 正常 npm install, require 之前发布的 npm 包, 不出意外, vscode 就应该能进行这个包的 api 提示了.

怎么? 还是没有提示?

如果没有提示, 检查项目目录下是否存在 jsconfig.json 文件, jsconfig.json 需要声明 compilerOptions > module 为 commonjs, 如下:

{
    "compilerOptions": {
        "target": "ES6",
        "baseUrl": ".",
        "module": "commonjs"
    }
}