Jsonz bug-log

后续更新会放在 github.com/jsonz1993/blog

0%

create-own-package

Posted on Edited on In

本文只是自己记录方便偶尔查阅，没有任何干货或阅读价值...

首先我们罗列一下，一个npm工具包需要包含哪些通用的内容

  • package.json √
  • dist目录 √
  • src目录 √
  • 开发服务（编译）√
  • example √
  • 单元测试
  • Readme and docs
  • eslint √
  • githook
  • 发布相关

package.json

首先，必要的字段有 “name” 和 “version”
建议直接用 npm init跑一遍就好，也可以偷个懒直接 npm init -y使用预设的默认值

可以在terminal上键入以下命令设置一些默认值
npm set init.author.email "jsonz@qq.com"
npm set init.author.name "jsonz"

version

可以参照
npm semantic versioning

总结一下就是 版本号为x.y.z：向后兼容的bug修复补丁递增z；向后兼容的features新功能递增y；破坏性改动递增x版本号

更详细的可以看 semver version

版本符号问题

常见的版本定义

  • version 相当于锁版本，只能安装该版本 “1.0.0”
  • >version
  • >=version
  • <version
  • <= version
  • version 小版本变动，比如 “1.0.1” 代表大于等于 1.0.1，且小于 1.1.0，既z版本变动
  • ^version 中版本与小版本变动，比如 “^1.0.1” 代表大于等于 1.0.1 且小于 2.0.0，既 y 与 z版本的变动
  • 1.0.x y版本任意
  • tag 比如 “latest”
  • path 本地的包 “file:../package1”

本地包不是手动写一个url，而是用 npm install /Filepath 去安装的

还有一些 url 相关的可以看 package.json dependencies url

最后补上一个特别实用的版本计算器
npm semver calculator

npm version 用法

在当前版本已经修改完之后，commit 更改
再根据改动跑 npm run major|minor|patch，该命令会处理几项任务

  1. 自动修改 package.json 的version
  2. 打个当前version的tag
  3. git commit 且提交信息为当前 version

devDependencies && dependencies && peerDependencies等等

一个是你项目的开发依赖，一个是你项目中的依赖
举个例子，我们项目里用到的 lodash属于 __dependencies__，而项目开发的时候用到的webpack 则属于 devDependencies

peer

对于一些需要准确安装peerDependencies的，可以利用 install-peerdeps，例如 npx install-peerdeps --dev eslint-config-airbnb就会安装 eslint-config-airbnb 前置依赖，eslint, eslint-plugin-import, eslint-plugin-react, eslint-plugin-react-hooks, and eslint-plugin-jsx-a11y。

engines

当前程序需要什么版本支持，比如

1
2
3
4
5
6
{
  "engines": {
    "node": ">=10.0.0",
    "npm": ">=6.0.0"
  }
}

dist-tag

https://docs.npmjs.com/adding-dist-tags-to-packages

比如最新的自动会打上一个 latest 标签，一般我们不需要去关注这一块的东西

description、keywords 包的描述

用于 npm search 匹配用户搜索的关键字

homepage 主页、文档

用于 npm home和 npm docs跳转的

bugs 问题反馈

用于 npm bugs跳转

license

@TODO 占坑展开几个比较常见的协议

author

可以是单行 <name> <email> (<homePage>) 也可以是对象形式，包含 name, email 和 url 三个字段

files

你的包包括哪一些文件，如果项目中有 .npmignore 则包含除了该文件外的其他文件，如果没有 __.npmignore__，但是有 .gitignore 则会用 __.gitignore__。 具体见 packages.json files

但是不管怎么设置都会包含这些文件

  • package.json
  • README
  • CHANGES / CHANGELOG / HISTORY
  • LICENSE / LICENCE
  • NOTICE
  • package.json main 字段包含的文件

main

配置一个文件路径，当别人引入你的模块时默认会加载这个文件。一般指向__”commonjs”__文件

browser

只能在浏览器使用的文件

module

引入 esm 模块的文件

https://rollupjs.org/guide/en/#outputformat

https://zhuanlan.zhihu.com/p/129310389

https://juejin.im/post/5cfe6d3be51d454d544abf30

https://github.com/SunshowerC/blog/issues/8

@TODO 补充更详细的介绍 esm commonjs main 等情况？ https://github.com/SunshowerC/blog/issues/8

bin

可执行文件，写在这里的可执行文件会被软链到 __node_module/.bin__下面。
比如 jest，当我们 npm install jest 之后，直接在当前目录执行 jest就会去跑 __node_module/jest`下面 package.json 的bin字段指定的可执行文件

package.json bin

repository

当前包的仓库， npm repo 时跳转

1
2
3
4
{
  "type": "git",
  "url": "https://github.com/jsonz1993/project.git"
}

config

占坑

README or Docs

README.md

README一般包含了最简单的使用教程，包括 安装、配置、使用等

如果你写的包有很多功能或接口的话，则推荐有 docs 模块介绍当前包的接口的，如果只是比较简单的接口，则可以也写在README.md

发布

.npmignore

对于不重要的东西，可以使用 .npmignore 避免上传到 npm 上，比如 .babelrc, .editorconfig, docs/, test/ 等等

.npmignore guide

.npmrc

.npmrc guide
当前项目的npm配置，会覆盖全局的 .npmrc，比如我发的是公司内部的私有包，可以在项目下新建一个 .npmrc。然后写上 registry 等字段

不再维护 or 弃用

如果说你不想再维护某个包，或者某个版本有严重bug，你不想用户去使用它，可以弃用该包。使用场景比较少，具体参照官方文档

常用的cli

npm bugs 直接打开反馈bug的网站

npm bugs react是打开react github repos 的issues

npm config

处理npm 配置相关问题

npm docs

npm docs react打开react 官网主页

占坑

npm repo 打开包的仓库

一般直接打开 github repo

开发服务（编译）

目前比较流行的 webpack,roolup,__parcel__和比较年轻的__snowpack__。

关于本地调试npm

在开发的npm包下面跑 npm link
在要用的地方跑 npm i packageName

调试完之后 开发的包下面 npm unlink
要用的地方 npm uninstall packageName && npm install packageName