npm package开发指南-包内容篇

Coder编程 2020-03-05

展开全文

假设我们要开发一个 npm 库，名字叫 lib-dev-tutorial，那么需要包含哪些内容？我们下面就来列举下，初始化目录结构如下:

lib-dev-tutorial
  ├── src -- 源码目录
  |    └── index.js
  ├── .gitignore
  └── package.json

package包含的内容

库的使用者使用的文件

如果开发人员安装了你的库，那么引入的时候找哪个文件？编译源码生成 dist/index.js，并在 package.json 中增加一个 main 字段指向这个文件。

lib-dev-tutorial
  ├── dist
  |    └── index.js
  ├── src -- 源码目录
  |    └── index.js
  ├── .gitignore
  └── package.json

{
  "main": "dist/index.js"
}

npm 始于 node，所以这个文件应该符合 commonjs 的模块规范。

符合ES Module的文件

现在支持运行原生 ES Module 的环境在变多，如果开发人员使用 ES Module 来编写程序。那么我们直接提供一个符合 ES Module 规范的文件，就不需要再把上一步中 commonjs 规范文件转成 ES Module 了。通过编译工具编译出使用 ES Module 规范的文件 es/index.js，并在 package.json 中增加一个 module 字段指向这个文件。

lib-dev-tutorial
  ├── es
  |    └── index.js
  ├── dist
  |    └── index.js
  ├── src -- 源码目录
  |    └── index.js
  ├── .gitignore
  └── package.json

很多库为了把上述两步的文件语义化区分，会把 dist 目录改成 lib，我们也遵循这个习惯：

lib-dev-tutorial
  ├── es
  |    └── index.js
  ├── lib
  |    └── index.js
  ├── src -- 源码目录
  |    └── index.js
  ├── .gitignore
  └── package.json

{
  "main": "lib/index.js",
  "module": "es/index.js"
}

通过script引用的文件

如果你希望自己的库健壮点，还可以提供 umd 模式的文件，让你的库可以直接在 html 上通过 script 标签引用。通过编译工具编译出文件 umd/index.js

lib-dev-tutorial
  ├── umd
  |    └── index.js
  ├── es
  |    └── index.js
  ├── lib
  |    └── index.js
  ├── src -- 源码目录
  |    └── index.js
  ├── .gitignore
  └── package.json

umd/index.js 要不要压缩按自己需求来决定。

类型声明文件

TypeScript 的使用已经异常广泛了，我们也增加一个自己库的类型声明文件。方法有三种：

把类型声明文件放到某一个目录下（譬如：typings/index.d.ts），并在 package.json 中增加 types 字段指向这个文件。

lib-dev-tutorial
  ├── umd
  |    └── index.js
  ├── es
  |    └── index.js
  ├── lib
  |    └── index.js
  ├── src -- 源码目录
  |    └── index.js
  ├── typings
  |    └── index.d.ts
  ├── .gitignore
  └── package.json

{
  "main": "lib/index.js",
  "module": "es/index.js",
  "types": "typings/index.d.ts"
}

注：package.json 中字段 types 也可以写成 typings，两者是等价的。

在库的根目录下直接放一个 index.d.ts，这个文件原则上不需要在 package.json 指定。但是推荐所有情况都在 package.json 指明类型声明文件的位置。

lib-dev-tutorial
  ├── umd
  |    └── index.js
  ├── es
  |    └── index.js
  ├── lib
  |    └── index.js
  ├── src -- 源码目录
  |    └── index.js
  ├── index.d.ts -- 原则上无需在 package.json 声明文件位置
  |
  ├── .gitignore
  └── package.json

单独编写类型声明文件，发布到 npm 上的 @types organization 下 @types/lib-dev-tutorial，这种方式开发者需要单独安装类型声明文件 npm install --save @types/lib-dev-tutorial

文档

READMD.md - 这个是作为你的库在 npm 网站上的主页。
CHANGELOG.md
LICENSE

lib-dev-tutorial
  ├── umd
  |    └── index.js
  ├── es
  |    └── index.js
  ├── lib
  |    └── index.js
  ├── src -- 源码目录
  |    └── index.js
  ├── typings
  |    └── index.d.ts
  |
  ├── .gitignore
  ├── package.json
  ├── README.md
  ├── CHANGELOG.md
  └── LICENSE

发布

package.json字段

以下是和发布到 npm 有密切关系的字段(但不仅限于这些字段)

name：库的名字。
version：库的版本号，发布的时候读取的就是这个字段。
author：库作者，会在 npm 网站库首页显示。
license：开源证书，会在 npm 网站库首页显示。
repository：代码库地址，会在 npm 网站库首页显示。
homepage：库的主页地址，会在 npm 网站库首页显示。
dependencies：你的库依赖的其他库，在开发者 install 你的库的时候会一并下载。

scoped库

如果你的库是公开库，则直接 npm publish 就可以了（对了 publish 前记得 login 噢~）。

如果你的库名是 @name/subname，说明你的库是 scoped，那么你还要做这些事情：

登录到 npm 网站，建立一个 @name 的组织：https://www./org/create （填写 organization name 的时候 @ 符号不用填），付费还是公开按需自己的需要。首次发布，如果不先建立，是发不上去的，会报 Scope not found。
如果你的库名是 @name/subname，且按公开库发布，在运行 npm 发布命令时要加参数：npm publis --access public
第二步中如果不加参数，请在 package.json 中加上如下字段：
```
{
  "publishConfig": {
    "access": "public"
  }
}
```