Creating your first Yarn Package with Git integration

A yarn package is a directory that has some code as well as a package.json file that gives Yarn information about the package.

Usually, whenever you create a package, you most likely want to enable some kind of version control system. The most commonly used version control is git however, yarn does not care the version control system you choose. In this tutorial we will be using the git version control system.

To continue with this tutorial, you will have to install yarn and git.

Creating your first package

For you to create your first package, you will need to run the following commands from your system's terminal:

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

This command will first initialize a git repository, then put you inside the repository, then it will open up an interactive form for creating a new yarn project with following questions:

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

For these questions, you can either hit enter to choose the defaults, or you answer them. You can also leave them blank.

Package.json

If you complete the dialogue above, you will get a package.json file similar to the one shown below:

{
  "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 <[email protected]>",
  "license": "MIT"
}

The fields that you see in the package.json have the following meanings:

• name field defines the identifier of your package.
• version field is the semver-compatible version of your package.
• description field is an optional but it is a recommended field that gets used by other Yarn users to search for and understand your project.
• main field is used to define the entry point of your code used by programs like Node.js.
• repository This is another optional field but it is recommended to help users of your package find the source code to contribute back.
• author field is the creator or maintainer of a package.
• license this is the published legal terms of your package.

Whenever you run the yarn init command, the package.json file will be created.

Additional fields

• keywords field is a list of terms that other developers can search for to find your package or related packages.
• homepage field defines a url to point users to a website.
• bugs field is a url to point users of your package to if they discover an issue with your package.
• contributors The contributors field provides a list of contributors to the package.
• files the file field defines a list of files that should be included in your package when published and installed.
• bin field defines a mapping of cli commands (binaries) for Yarn to create for the package when installing it.

Listing and open source

Yarn packages owners are advised to keep their packages open source, but you should note that the packages are not open source by default.

If you want to make a package open source, you will need to choose an open source license for it, the commonly used ones are:

• Apache License 2.0
• GNI General Public License 3.0
• MIT License

Code Sharing

If you want to permit the users of your package to be able to access your source code or you want to provide a way for them to report issues. You can use any of these websites to host your code:

• Bitbucket
• GitHub
• GitLab

Once you host your source code, you should update the repostitory field of your package.json file to reflect the url.

Documentation

It is recommended that you should write your documentation before you publish the package. At a minimum, it is advisable that you write a README.md file in the root of your project that will introduce your package and document the public API.

Keep packages small

When you are creating Yarn packages, it is advisable that you keep things as simple and small.

Previous: Pruning an Offline Mirror in Yarn for optimized builds.
Next: How to Publish your Yarn Package to the npm Registry.