🗒️贡献 package

来自官网，向 registry 贡献 packages

1. 创建和发布

1.1 创建 package.json

发布到 registry 里的 package 必须包含 package.json 文件。

执行 npm init，创建一个新的 package.json 文件。

{
  "name": "hello-world",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC"
}

1. name（必填）：package 的名字，必须是一个小写的单词，可以包含连字符 - 和下划线 _

   • 需唯一、有描述性

   • 需符合 npm 政策指南（比如不冒犯、不侵权商标）

2. version（必填）：格式必须是 x.x.x，遵循 semantic versioning rules

3. description（建议有）：便于在 npm website 更容易被搜到

4. author：格式 Your Name <[e-mail]> (http://example.com)

   • email 和 website 都是可选的

npm init --yes # 从当前目录中提取默认值
npm init -y    #

从当前目录中提取的默认值有：

1. name 当前目录名

2. version 总是 "1.0.0"

3. description 来自 README 的信息，或者一个空字符串 ""

4. scripts: 默认情况下创建一个空 test 脚本

5. keywords 空

6. author 空

7. license 是 "ISC"

8. bugs 来自当前目录的信息，如果存在的话

9. homepage 来自当前目录的信息，如果存在的话

也可以为 init 命令设置默认 config options，比如：

npm set init-author-email "[e-mail]"
npm set init-author-name "example_user"
npm set init-license "MIT"

关于 npm init 的高级用法，可查阅 init-package-json GitHub repository。

1.2 创建 Node.js 模块

Node.js modules 是一种可以发布到 npm 的 package。

1. 运行 npm init 创建一个 package.json 文件

   • 对于 unscoped modules，运行 npm init

   • 对于 scoped modules，运行 npm init --scope=@scope-name

2. 创建一个当别人用这个 module 时要 load 的文件

3. 运行 npm publish 把 package 发布到 npm

4. 测试 module

   • 在一个项目里 npm install <your-module-name>

   • 创建 test.js，在里面 require 那个 module 并调用其方法

   • 运行 node test.js

// <your-module-name> 文件
exports.say = function() {
  console.log("Hello from the demo package");
}

// test.js
const demo = require('your-module-name')
console.log(demo.say())

1.3 创建 README.md

建议 package 的目录包含一个 README 文件，一是方便其他人在 npm 上找到该 package，还能提供良好的使用体验。通常，README 文件包含与 install, configure 和 use 相关的说明以及其它有用信息。README 文件会显示在 package 的页面上。

npm package README 文件必须位于 package 的根目录中。

当我们发布新版本的 package 时，README 文件只会在 package 页面上更新。要更新 README 文件的内容，可运行以下命令：

npm version patch
npm publish

1.4 发布 packages

1. unscoped public packages：只能通过 package name 来引用

2. scoped public packages：在 user 或 organization 的命名空间中公开 package 的代码

   • 将 user-scoped 或者 organization-scoped 的公共 packages 发布到 npm registry

3. private packages：与一组特定的用户或团队共享 packages 代码

   • 将 user-scoped 或者 organization-scoped 的私有 packages 发布到 npm registry

发布要求：

package 类型	npm user account	npm organization
unscoped public	✔️	--
user-scoped public	✔️	--
organization-scoped public	✔️	✔️
user-scoped private	✔️ 付费	--
organization-scoped private	✔️	✔️ 付费

步骤：

1. 运行 npm init 创建一个 package.json 文件

2. 创建一个 README.md 文件

3. 检查 package 的内容，不要有敏感信息和不必要的信息

4. 测试 package：安装成功后，在代码里 require("my-package") 测试下

5. 运行 npm publish 发布 package

   • 登录 user account

     • npm login

     • npm whoami

   • 登录 organization

# 1. 创建 package.json 文件
npm init
npm init --scope=@my-org
npm init --scope=@my-username

# 2. 测试：发布之前确保 package 可以正在安装和工作
npm install . -g  # 全局安装，在 package 的 root 执行 

cd ../some-other-folder   # 本地安装
npm install ../my-package # 本地安装
 
npm link    # 安装 development package 并实时查看更改，而不用 re-install 它
npm ls -g   # 看是否有该 package


# 3. 发布
npm publish
npm publish --access public

2. 更新和管理

更新和管理已发布的 packages。

2.1 更新 visibility

我们只能更改 scoped package 的可见性（visibility），但不可以更改 unscoped package 的可见性。

1. 将 public 变 private（变成 private 要收费）

   • 如果想要限制 public package 的 access 和 visibility，就可以将其变为 private

   • 当将 public package 设为 private 时

     • 其 access 会立即更新

     • 而 visibility 需要过几分钟后才能生效（它会从网站上 removed）

2. 将 private 变 public

可以通过 website，可以通过 command line。

npm access restricted <package-name> # public → private
npm access public <package-name>     # private → public

2.2 更新 version

1. 更改 package.json 里的版本号

2. 运行 npm version <update_type>，其中 <update_type> 是语义版本控制的发布类型，比如 patch, major, minor

3. 运行 npm publish

4. 去网站上查看版本是否生效

2.3 unpublish 取消发布

unpublish 是从 registry 中完全删除 package，其他用户就不能再 install 它了。

unpublish 需要满足的条件：

1. npm Public Registry 里没有其他 packages 依赖它

   • 对于新创建的 packages，只要满足这条就可以在发布后的 72 hours 内随时 unpublish

2. 上周的下载量少于 300 次（超过 72 小时的）

3. 有一个 owner/maintainer（超过 72 小时的）

可以在网站上操作，也可以用 CLI。

npm unpublish <package_name>@<version> # 特定版本
npm unpublish <package_name> --force   # 所有版本
npm unpublish <package-name> -f

一旦 unpublish 了，那么 24 小时之内再不能以相同的名字 republish 了。所以如果是不小心 unpublish 的，那么可以换个不同的名字或版本号。

操作	场景
unpublish	不小心发布了些东西 想测试 npm 发布了不打算 public 的内容 想 rename package（只能用新名字 re-publish）
deprecate	不想再维护 package，但用户依然能 install 它 npm Public Registry 里还有其它 package 依赖了它 不满足 unpublish 条件的，可以考虑 deprecate 它

2.4 deprecate 弃用

如果不想再维护 package 了，或是想鼓励用户更新到一个新的或者不同的版本，那我们可以弃用（deprecate）它。弃用 package 或其某个版本了之后，当用户在 install 它时会在终端打印一条消息。

弃用的 warning 或 message 可以写任何东西，比如鼓励用户更新到特定版本或替代 package。（unpublish 时没有 warning）。

可以在网站上操作，也可以在命令行。

# deprecate
npm deprecate <package-name> "<message>"
npm deprecate <package-name>@<version> "<message>"

# undeprecate，取消弃用，把上面的 message 置空字符串即可
npm deprecate <package-name> ""
npm deprecate <package-name>@<version> ""

如果不想再维护 package，还想把它从自己的 user profile 中删除（remove）了，但还有其他用户在依赖这个 package，那我们可以将它转移到 @npm 这个 user account 上。一旦转移过去，我们再没法 update 它了。

# ransfer a package to the npm user account
npm owner add npm <package-name>
npm owner rm <user> <package-name>

2.5 添加 collaborators

2.6 转给另一个 user account

3. .npmignore

使用 .npmignore 文件将内容排除在 package 之外。

• 如果没有 .npmignore 文件，npm 将会使用 .gitignore 文件

• 如果想包含被 .gitignore 排除的文件，那就创建 .npmignore 文件来覆盖它

与 git 一样，npm 会在 package 的所有子目录中查找 .npmignore 和 .gitignore 文件，不仅仅是根目录。模式规则也和 git 的一样，详见 Git / Ignoring Files。

默认情况，以下 paths 和 files 会被忽略，所以就没有必要显式添加了。

• .*.swp

• ._*

• .DS_Store

• .git

• .gitignore

• .hg

• .npmignore

• .npmrc

• .lock-wscript

• .svn

• .wafpickle-*

• config.gypi

• CVS

• npm-debug.log

• node_modules：它里的全部内容都会被忽略，除了 bundled dependencies（当然这部分 npm 会自动处理）

如果想测试 npmignore 是否生效，可以在本地运行 npm pack 命令，它会在工作目录生成一个 tarball，就像发布时一样。

4. 主要参考

• Packages and modules / Contributing packages to the registry

• npm CLI / Using npm / Developers