创建一个包

由项目代码和一个向Yarn提供包信息的 package.json 文件组成。

大部分的包都使用了版本控制系统,最常见的是git。但 Yarn 对此并不做要求,你可随意选择。本指南以git为例。

注意: 如果打算照着本指南实践,请先安装 gitYarn

创建你的第一个包

想要创建你的第一个包,打开系统终端/控制台并运行以下命令:

git init my-new-project
cd my-new-project
yarn init

这些命令会创建一个新的 git 仓库,并切换其为当前工作目录,然后显示一个包含以下问题的交互式表单,用于创建一个新的 yarn 项目:

name (my-new-project):
version (1.0.0):
description:
entry point (index.js):
git repository:
author:
license (MIT):

你既可以回答这些问题,也可以直接敲回车键(enter/return)使用默认配置或者留空。

提示: 如果打算所有的问题都使用默认配置,你也可以运行 yarn init --yes,这会跳过所有问题。

package.json

现在应该创建了一个和下面文件内容类似的 package.json

{
  "name": "my-new-project",
  "version": "1.0.0",
  "description": "My New Project description.",
  "main": "index.js",
  "repository": {
    "url": "https://example.com/your-username/my-new-project",
    "type": "git"
  },
  "author": "Your Name <you@example.com>",
  "license": "MIT"
}

package.json 里的字段含义如下:

  • name 是包的标识,如果你打算把它发布到全局registry,请确保这个标识是唯一的。
  • version 是语义版本号(semver),包可以被发布任意多次,但每次发布必须包含新的版本号。
  • description是包的描述,用以让其他 Yarn 用户搜索并了解你的项目,这个字段非必须,但推荐填写。
  • main 用来定义会被 Node.js 这类程序使用的代码入口,默认值为 index.js
  • repository 可以帮助其他用户找到包的代码托管处,并为其做贡献,这同样是一个可选但推荐填写的字段。
  • author 是包的创建者或维护者,遵循 "Your Name <you@example.com> (http://your-website.com)" 这样的格式。
  • license 是包发布的法律条款,以及什么是包代码的许可用法。

yarn init 的运行结果除了创建此文件之外,没有任何副作用,你可以自由编辑此文件。

附加字段

我们来看看 package.json 有哪些附加字段:

{
  "name": "my-new-project",
  "...": "...",
  "keywords": ["cool", "useful", "stuff"],
  "homepage": "https://my-new-project-website.com",
  "bugs": "https://github.com/you/my-new-project/issues",
  "contributors": [
    "Your Friend <their-email@example.com> (http://their-website.com)",
    "Another Friend <another-email@example.com> (https://another-website.org)"
  ],
  "files": ["index.js", "lib/*.js", "bin/*.js"],
  "bin": {
    "my-new-project-cli": "bin/my-new-project-cli.js"
  }
}
  • keywords 是关键字列表,帮助其他开发者进行搜索。
  • homepage 是项目的主页,包含包的简介、文档和其他附加资源链接。
  • bugs 是帮助用户了解包现有问题的URL链接。
  • contributors 是包的贡献者列表,如果有别人参与你的项目,你可以在这里指明。
  • files 是包发布和安装时应该包含的文件列表,如果不指定,Yarn 会列出项目中的所有文件。
  • bin 是一个让 Yarn 在包安装时给包创建 cli 命令(二进制)的映射表。

要得到 package.json 所有字段以及上面那些字段的更详细信息,请参阅 package.json 文档

许可证和开源

通常来说,Yarn 鼓励将包 开源,但要注意的是,开源指的不是简单的发布。

开源许可证是开源代码必需的,有很多许可证可供选择,以下是最常见的几个:

这个链接里有更多的选项。

选择好开源许可证以后,请在包的根目录下添加包含许可证文本的 LICENSE 文件,并更新 package.json 文件的 license 字段。

注意:如果不想开源,你应该指明授权方式。

共享代码

你可以将代码托管在以下几个流行的网站,以方便其他用户访问以及报告问题:

用户通过上述网站可以查看代码、报告问题、贡献力量。代码被托管妥当后,请更新 package.json 文件的以下字段:

{
  "homepage": "https://github.com/username/my-new-project",
  "bugs": "https://github.com/username/my-new-project/issues",
  "repository": {
    "url": "https://github.com/username/my-new-project",
    "type": "git"
  }
}

文档

理想情况下,你应该在包发布之前撰写文档。 起码应该在项目根目录下放置 README.md 文件,包含包的简介和对外的API描述。

良好的文档应该为用户指明上手方法,以及如何深度使用。 让自己站在小白用户的立场上思考。 文档要详细准确,同时尽可能简单易懂。 有高质量文档的项目更容易成功。

越小越好

我们鼓励创建小巧简单的Yarn包。 只要可以,就尽可能把较大的包拆分成较小的包。 拆分的原因是,Yarn可以高效地安装成百上千数量的包。

“大量小包”是包管理的最佳实践之一,这会使下载大小更小,因为这样做避免了打包体积巨大的代码,却仅使用到了其中很小一部分。

还要记得留意包里的文件内容, 不要无意间发布用于测试的代码,或者其他与包的正常使用无关的内容,比如构建脚本、图片等。

同时留意包的依赖,能少则少。不要无意间引入大型依赖项目。