• 创建你的第一个包
  • package.json
    • 附加字段
  • 许可证和开源
  • 共享代码
  • 文档
  • 越小越好

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

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

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

    创建你的第一个包

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

    1. git init my-new-project
    2. cd my-new-project
    3. yarn init

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

    1. name (my-new-project):
    2. version (1.0.0):
    3. description:
    4. entry point (index.js):
    5. git repository:
    6. author:
    7. license (MIT):

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

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

    package.json

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

    1. {
    2.   "name": "my-new-project",
    3.   "version": "1.0.0",
    4.   "description": "My New Project description.",
    5.   "main": "index.js",
    6.   "repository": {
    7.     "url": "https://example.com/your-username/my-new-project",
    8.     "type": "git"
    9.   },
    10.   "author": "Your Name <you@example.com>",
    11.   "license": "MIT"
    12. }

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

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

    附加字段

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

    1. {
    2.   "name": "my-new-project",
    3.   "...": "...",
    4.   "keywords": ["cool", "useful", "stuff"],
    5.   "homepage": "https://my-new-project-website.com",
    6.   "bugs": "https://github.com/you/my-new-project/issues",
    7.   "contributors": [
    8.     "Your Friend <their-email@example.com> (http://their-website.com)",
    9.     "Another Friend <another-email@example.com> (https://another-website.org)"
    10.   ],
    11.   "files": ["index.js", "lib/*.js", "bin/*.js"],
    12.   "bin": {
    13.     "my-new-project-cli": "bin/my-new-project-cli.js"
    14.   }
    15. }
    • keywords 是关键字列表，帮助其他开发者进行搜索。
    • homepage 是项目的主页，包含包的简介、文档和其他附加资源链接。
    • bugs 是帮助用户了解包现有问题的URL链接。
    • contributors 是包的贡献者列表，如果有别人参与你的项目，你可以在这里指明。
    • files 是包发布和安装时应该包含的文件列表，如果不指定，Yarn 会列出项目中的所有文件。
    • bin 是一个让 Yarn 在包安装时给包创建 cli 命令（二进制）的映射表。
      要得到 package.json 所有字段以及上面那些字段的更详细信息，请参阅 package.json 文档。

    许可证和开源

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

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

    • MIT License
    • Apache License 2.0
    • GNU General Public License 3.0
      这个链接里有更多的选项。

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

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

    共享代码

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

    • GitHub
    • GitLab
    • Bitbucket
      用户通过上述网站可以查看代码、报告问题、贡献力量。代码被托管妥当后，请更新 package.json 文件的以下字段：
    1. {
    2.   "homepage": "https://github.com/username/my-new-project",
    3.   "bugs": "https://github.com/username/my-new-project/issues",
    4.   "repository": {
    5.     "url": "https://github.com/username/my-new-project",
    6.     "type": "git"
    7.   }
    8. }

    文档

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

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

    越小越好

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

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

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

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

    原文: https://yarnpkg.com/zh-Hans/docs/creating-a-package