假设我们要开发一个 npm 库,名字叫 lib-dev-tutorial,那么需要包含哪些内容?我们下面就来列举下,初始化目录结构如下:
lib-dev-tutorial ├── src -- 源码目录 | └── index.js ├── .gitignore └── package.json
如果开发人员安装了你的库,那么引入的时候找哪个文件?编译源码生成 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 规范的文件,就不需要再把上一步中 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"}
如果你希望自己的库健壮点,还可以提供 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
,两者是等价的。
lib-dev-tutorial ├── umd | └── index.js ├── es | └── index.js ├── lib | └── index.js ├── src -- 源码目录 | └── index.js ├── index.d.ts -- 原则上无需在 package.json 声明文件位置 | ├── .gitignore └── package.json
@types/lib-dev-tutorial
,这种方式开发者需要单独安装类型声明文件 npm install --save @types/lib-dev-tutorial
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
以下是和发布到 npm 有密切关系的字段(但不仅限于这些字段)
如果你的库是公开库,则直接 npm publish
就可以了(对了 publish 前记得 login 噢~)。
如果你的库名是 @name/subname,说明你的库是 scoped,那么你还要做这些事情:
npm publis --access public
第二步中如果不加参数,请在 package.json 中加上如下字段:
{ "publishConfig": { "access": "public" }}
最后稍微说下你会在代码库中还会包含点什么文件。
使用持续集成服务,譬如 travis,你会有配置文件 .travis.yml
会有 .github 文件夹,下面会有些访问 github 如何展示 issue 等页面的配置文件。
各种 ignore 文件,各种工程化配置文件。各种 demo/example,各种测试相关文件,等等等等。
本篇是笔者对自己开发工作的梳理总结,如果有遗漏其他比较关键的部分,欢迎大家指正。
联系客服