Lean's blog

package.json cook-book

December 22, 2019

建一个 package.json 的索引供查看,下面以 npm 为例子,实际上 yarn 也是通用的

[TOC]

name

name 作为 npm 包的名字,不能有大写字母,个人建议命名采用字母数字和_ -,也可以有一个 scope 作为前缀,比如@myorg/mypackage

version

npm 包的版本号,遵循 semver 规范,也可以看 semver 语义扫盲

另:npm 在发布的时候还可以添加tag,比如npm publish --tag beta,然后在安装的时候只需要npm install [email protected] 即可。

description

项目描述,使用npm search 或在npm 官网搜索结果会展示

keywords

关键字,使用npm search 或在npm 官网搜索结果会展示

homepage

项目首页

bugs

提 issue 的地址

license

如果不想其他人用的话就设置为UNLICENSED常用 liscence 列表

author contributers

author设置一个人,contributers 设置为一群人,格式为

{ "name" : "Barney Rubble"
, "email" : "[email protected]"
, "url" : "http://barnyrubble.tumblr.com/"
}

另外如果在包的根路径上有 AUTHORS 文件,会以Name <email> (url) 格式解析为 contributers

files

作为依赖时要包含哪些文件,也可以使用.npmignore忽略文件,根目录下的.npmignore不会覆盖files,子目录下的会(尚未亲自验证)。没有.npmignore的话默认会使用.gitignore

肯定会包括的文件

  • package.json
  • README
  • CHANGES / CHANGELOG / HISTORY
  • LICENSE / LICENCE
  • NOTICE
  • The file in the “main” field

main

require('foo')时,返回的导出对象的文件位置

bin

将命令添加到PATH里面,这样就能直接执行命令,bin 文件要以#!/usr/bin/env node 开头,bin的格式

{
  "bin": "bin.js", // 命令将直接以 project name 命名
  "bin": {
    "command-name": "bin/command-name.js",
    "other-command": "bin/other-command"
  }
}

另外在 win 下写的命令有坑,TODO: 之后写坑

man

使用 man 命令时展示的文件

{
  "man": "./man/doc.1",
  "man": ["./man/doc.1", "./man/doc.2"]
}

directories

commonjs 风格的使用目录结构指示文件结构,没啥用

repository

代码地址

scripts

可以自定义需要运行的脚本命令,也默认支持一些 npm 生命周期钩子,详情见npm-scripts 几个常用的如下

  • prepare: 会在 npm pulish npm install 之前触发,原来的prepublish 功能一样,但是将会废弃,详情见prepublish issue
  • prepublishOnly: 只会在npm publish之前触发
  • publish, postPublish: 会在npm publish之后触发

另外任意的自定义命令可以加上 pre 与 post,指定这个命令执行之前做什么,之后做什么

{
  "scripts": {
    "foo": "echo foo",
    "prefoo": "echo prefoo",
    "postfoo": "echo postfoo"
  }
}

config

在使用 yarn 或者 npm 运行时可以通过 process.env.npm_package_ 访问到 package.json 里面的字段,通过 process.env.npm_config_ 访问到 config 设置,通过process.env.npm_package_config访问到 config 对象,config 对象设置例子:

{
  "config" : { "port" : "8080" }
}

dependencies

要安装的依赖,依赖的版本遵循 semver 规范,如果是要发布的包的话,其他人安装你的包的时候也会安装 dependencies 里面的包,所以把那些测试,编译等开发时候才用到的依赖放到 devDependencies 里面。

在添加依赖的时候,如果没有指定特定的版本号的话,会默认安装最新的,而且依赖版本表示为^1.1.9这种类型。几种依赖表示方法如下:

^1.0.1 等价于1.x

1.0.1 则是表示精确的版本号

~1.0.1等价于1.0.x

在 npm install 的时候总是会安装依赖版本范围内最新的版本。

另外如果本地写了一个包,想在本地其他地方引用的话,可以使用 npm install file:../path/test 来安装本地包,或者直接写在 package.json 里面在 npm install。还有一种情况就是如果已经安装了包,但是本地进行了修改然后想进行测试的话,这种情况下可以使用 npm link ,操作示例如下

// test1: 要引用的包 test2: require("test1")
// 在 test1 下使用,可以将当前的包以及 bin 命令添加到全局
npm link
// 在 test2 根目录下使用, 会与全局的 node_modules 的 test1链接文件建立链接
npm link test1
// 注销全局的链接,需要在 test1 根目录下使用
npm unlink
// test2 不再链接 test1,在 test2 根目录下使用
npm unlink test1

另外也可以直接 npm link /path/to/test1,但要想注销全局的链接还是得到test1 根目录下 unlink。

devDependencies

开发中使用的依赖

peerDependencies

用来表示包在哪种宿主环境下使用,比如一个在 react 16.x 中使用的包可以这么表示依赖

{
  "peerDependencies": {
    "react": "16.x"
  }
}

engines

可以用来制定 node 版本,npm 版本{ "engines" : { "node" : ">=0.10.3 <0.12" } }

private

为 true 的时候,npm publish不能执行

publishConfig

npm publish 的时候用来指定 “tag”, “registry” and “access” 的配置

特殊的配置


lean

Personal blog by Lean. I'm a front end coder.