Creating a Package
A package is a directory with some code and a package.json
file that
provides information to Yarn about your package.
Most packages use some kind of version control system. The most common one is git but Yarn doesn’t mind whatever one you choose to use. For this guide, our examples are going to use git.
Note: If you want to follow along with this guide, be sure to first install git and Yarn.
Creating your first package
In order to create your first package, open up your system terminal/console and run the following commands:
git init my-new-project
cd my-new-project
yarn init
This is going to create a new git repository, put you inside of it, and then open up an interactive form for creating a new yarn project with the following questions:
name (my-new-project):
version (1.0.0):
description:
entry point (index.js):
git repository:
author:
license (MIT):
You can type answers for each of these or you can just hit enter/return to use the default or leave it blank.
Tip: If you want to use the defaults for everything you can also run
yarn init --yes
and it will skip all the questions.
package.json
Now you should have a package.json
that looks similar to this:
{
"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"
}
The fields you see in the package.json
have the following meanings:
- name is the identifier of your package, if you are going to publish it to the global registry, you need to be sure that it is unique.
- version is the semver-compatible version of your package, you can publish a package as much as you want but they must have new versions.
- description is an optional but recommended field that gets used by other Yarn users to search for and understand your project.
- main s used to define the entry point of your code used by packagers or development environments as NodeJS. If unspecified it will default to
index.js
. - repository is another optional but recommended field that helps users of your package find the source code to contribute back.
- author is the creator or maintainer of a package. It follows the format
"Your Name <you@example.com> (https://your-website.com)"
- license is the published legal terms of your package and what is the allowed usage of the code in your package.
Today package.json supports the “exports” entry point which is taken over “main” entry point if it is defined. When you run
yarn init
, all it is doing is creating this file, nothing happens in the background. You can feel free to edit this file as much as you want.
Additional fields
Let’s go through some additional package.json
fields you might want to add.
{
"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> (https://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 is a list of terms that other developers can search for to find your package or related packages.
- homepage is a url to point users to a website that informs them on the package with an introduction, documentations, and links to additional resources.
- bugs is a url to point users of your package to if they discover an issue with your package.
- contributors is a list of contributors to the package. If there are other people involved in your project, you can specify them here.
- files is a list of files that should be included in your package when published and installed. If unspecified Yarn will include every file.
- bin is a mapping of cli commands (binaries) for Yarn to create for the package when installing it.
For a complete list of all the package.json
fields and more details about
each of the above fields please see the
package.json
documentation.
Licensing and open source
Yarn packages are generally encouraged to be open source, however it’s important to note that they aren’t inherently open source by simply publishing them.
In order for code to be open source it needs to have an open source license. There are many open source licenses to choose from, here are a couple of common ones:
If you want more options, you can get a more complete list here.
When you select an open source license for your package, be sure to add a
LICENSE
file in the root of your package with the license text and update
your package.json
license
field.
Note: If you do not want your project to be licensed as an open source project, you should be explicit about what the licensing is or if it is unlicensed.
Code sharing
You will likely want to allow users of your package to be able to access your source code and have a way to report issues. There are a couple of popular websites for hosting your code:
These sites will allow your users to see your code, report issues, and
contribute back. Once you have your code up somewhere you should add the
following fields to your 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"
}
}
Documentation
You should ideally write your documentation before you go publishing your
package. At a minimum you should write a README.md
file in the root of your
project that introduces your package and documents the public API.
Good documentation is defined by giving users all the knowledge they’ll need to get started with your project and continued use of it. Think about the questions someone who knows nothing about your project will have. Describe things accurately and as detailed as necessary, but also try to keep it brief and easy to read. Projects with high quality documentation are far more successful.
Keep packages small
When creating Yarn packages, you are encouraged to keep them small and simple. Break large packages into many small ones if it makes sense to do so. This is highly encouraged as Yarn is capable of installing hundreds or even thousands of packages very efficiently.
Many small packages are a great model of package management. Often this leads to smaller download sizes because you aren’t bundling massive dependencies and only using a small piece of it.
You should also consider the contents of your package. Make sure you aren’t accidentally distributing your tests or any other files that aren’t necessary for using your package (build scripts, images, etc).
Also be careful of what packages you are depending on, prefer smaller dependencies unless you have a good reason not to. Be certain that you aren’t accidentally depending on something massive.