Kai Soong

npm package 开发指南-包内容篇 ​

假设我们要开发一个 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

TIP

很多库为了把上述两步的文件语义化区分，会把 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"
}

TIP

注：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，那么你还要做这些事情：

  1. 登录到 npm 网站，建立一个 @name 的组织：https://www.npmjs.com/org/create （填写 organization name 的时候 @ 符号不用填），付费还是公开按需自己的需要。首次发布，如果不先建立，是发不上去的，会报 Scope not found。

  2. 如果你的库名是 @name/subname，且按公开库发布，在运行 npm 发布命令时要加参数：npm publis --access public

  3. 第二步中如果不加参数，请在 package.json 中加上如下字段：

{
      "publishConfig": {
        "access": "public"
      }
 }

和 package 无关 最后稍微说下你会在代码库中还会包含点什么文件。

持续集成 ​

使用持续集成服务，譬如 travis，你会有配置文件 .travis.yml

github ​

会有 .github 文件夹，下面会有些访问 github 如何展示 issue 等页面的配置文件。

其他 ​

各种 ignore 文件，各种工程化配置文件。各种 demo/example，各种测试相关文件，等等等等。

npm 安装 发布/更新/撤销发布包 ​

发布包之前你首先要有一个 npm 的账号

第一次发布包： 在终端输入 npm adduser，提示输入账号，密码和邮箱，然后将提示创建成功

非第一次发布包： 在终端输入 npm login，然后输入你创建的账号和密码，和邮箱，登陆

WARNING

  1. npm adduser 成功的时候默认你已经登陆了，所以不需要再接着 npm login.
  2. 不能和已有的包的名字重名！
  3. 还有一点要注意的是 npm 对包名的限制：不能有大写字母/空格/下滑线!
  4. 你的项目里有部分私密的代码不想发布到 npm 上？ 将它写入.gitignore 或.npmignore 中，上传就会被忽略了

撤销发布包 ​

sh
npm unpblish [xxx] --force

TIP

没有 xxx 默认撤销这个版本

  1. 根据规范，只有在发包的 24 小时内才允许撤销发布的包（ unpublish is only allowed with versions published in the last 24 hours）
  2. 即使你撤销了发布的包，发包的时候也不能再和被撤销的包的名称和版本重复了（即不能名称相同，版本相同，因为这两者构成的唯一标识已经被“占用”了）

npm 更新发布后的包： ​

事实上 npm 更新包和发布包的命令是一样的，都是 npm publish,不同之处在于，你需要修改包的版本

所以步骤是：

  1. 修改包的版本（package.json 里的 version 字段）

  2. npm publish

修改版本的细节： ​

npm 有一套自己的版本控制标准——Semantic versioning（语义化版本）

在我们的package.json里面有一个 version字段。那么，怎么在项目不断构建的过程中调整版本呢？

具体体现为：

对于 version:x.y.z

  1. 修复 bug,小改动，增加 z
  2. 增加了新特性，但仍能向后兼容，增加 y
  3. 有很大的改动，无法向后兼容,增加 x

例如：我原本的项目是 1.0.0 版本的话

若是 1 中情况，变为 1.0.1

若是 2 中情况，变为 1.1.0

若是 3 中情况，变为 2.0.0

通过 npm version <update_type>自动改变版本

update_type 为 patch, minor, or major 其中之一，分别表示补丁，小改，大改

scripts 使用 source 命令 ​

在 package.json 中，通过 npm run 执行的脚本会在不同的 shell 中运行，这就导致在第一个 shell 中激活的虚拟环境在第二个 shell 中不可用。为了在同一个 shell 中执行所有命令，您可以使用 bash -c 来确保在同一个 Bash 环境中运行所有命令。

json
{
  "scripts": {
    "dev": "bash -c 'source ./.venv/bin/activate && sanic main:app --host=0.0.0.0 --port=8001'"
  }
}