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
,那么你还要做这些事情:
登录到 npm 网站,建立一个 @name 的组织:https://www.npmjs.com/org/create (填写 organization name 的时候 @ 符号不用填),付费还是公开按需自己的需要。首次发布,如果不先建立,是发不上去的,会报 Scope not found。
如果你的库名是
@name/subname
,且按公开库发布,在运行 npm 发布命令时要加参数:npm publis --access public
第二步中如果不加参数,请在
package.json
中加上如下字段:
{
"publishConfig": {
"access": "public"
}
}
和 package 无关 最后稍微说下你会在代码库中还会包含点什么文件。
持续集成
使用持续集成服务,譬如 travis
,你会有配置文件 .travis.yml
github
会有 .github
文件夹,下面会有些访问 github
如何展示 issue
等页面的配置文件。
其他
各种 ignore
文件,各种工程化配置文件。各种 demo/example
,各种测试相关文件,等等等等。
npm 安装 发布/更新/撤销发布包
发布包之前你首先要有一个 npm 的账号
第一次发布包: 在终端输入 npm adduser
,提示输入账号,密码和邮箱,然后将提示创建成功
非第一次发布包: 在终端输入 npm login
,然后输入你创建的账号和密码,和邮箱,登陆
WARNING
npm adduser
成功的时候默认你已经登陆了,所以不需要再接着npm login
.- 不能和已有的包的名字重名!
- 还有一点要注意的是 npm 对包名的限制:不能有大写字母/空格/下滑线!
- 你的项目里有部分私密的代码不想发布到 npm 上? 将它写入
.gitignore
或.npmignore
中,上传就会被忽略了
撤销发布包
npm unpblish [xxx] --force
TIP
没有 xxx 默认撤销这个版本
- 根据规范,只有在发包的 24 小时内才允许撤销发布的包( unpublish is only allowed with versions published in the last 24 hours)
- 即使你撤销了发布的包,发包的时候也不能再和被撤销的包的名称和版本重复了(即不能名称相同,版本相同,因为这两者构成的唯一标识已经被“占用”了)
npm 更新发布后的包:
事实上 npm 更新包和发布包的命令是一样的,都是 npm publish,不同之处在于,你需要修改包的版本
所以步骤是:
修改包的版本(package.json 里的 version 字段)
npm publish
修改版本的细节:
npm 有一套自己的版本控制标准——Semantic versioning(语义化版本)
在我们的package.json
里面有一个 version
字段。那么,怎么在项目不断构建的过程中调整版本呢?
具体体现为:
对于 version:x.y.z
- 修复 bug,小改动,增加 z
- 增加了新特性,但仍能向后兼容,增加 y
- 有很大的改动,无法向后兼容,增加 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 环境中运行所有命令。
{
"scripts": {
"dev": "bash -c 'source ./.venv/bin/activate && sanic main:app --host=0.0.0.0 --port=8001'"
}
}