Yarn 创建包

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

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

注意：如果打算照着本指南实践，请先安装 git 和 Yarn。

创建你的第一个包

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

git init my-new-projectcd 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可以高效地安装成百上千数量的包。

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

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

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