Understanding Versions and dependencies in Yarn

In this tutorial, you will learn how to work with versions of dependencies.

Semantic Versioning

All the packages in Yarn follow semantic Versioning, which is also known as semver. Anytime you install a new pacakage from the registry, the package will be added to your package.json file along with a semver version range.

The semantic versions are divided into major.minor.patch and will look like any of these: 3.14.1, 0.42.0, 2.7.18. Every part of the version will get increment at various times:

• You should increment major when you make a breaking or incompatible change to the API of your package.
• You should increment minor when you add new functionality while staying backwards-compatible
• Finally, you should increment patch when you make bug fixes while staying backwards-compatible

Developers are referring to the minor and patch versions whenever they are talking about two semver versions being backward-compatible with one another.

Version ranges

If you want to specify a dependency, you should specify its name and a version range in your package.json as shown below:

{
  "dependencies": {
    "package-1": ">=2.0.0 <3.1.4",
    "package-2": "^0.4.2",
    "package-3": "~2.7.1"
  }
}

You can observe that there are a bunch of characters that are separate from the version. These characters, >=, <, ^ and ~, are operators and they are used when you want to specify version ranges.

The aim of adding version ranges is to specify which versions of a dependency works for your code.

Comparators

Every version range is made up of comparators. A comparator is simply an operator followed by a version. The table below shows some basic operators:

Intersections

You can join comparators with whitespace to create a comparator set. This will create an intersection of the comparators that it includes. For instance, A comparator set of >=2.0.0<3.1.4 means "Greater than or equal to" 2.0.0 and less than 3.1.4.

Unions

A full version range can also include a union of multiple comparator sets which are joined together by ||. If any side of the comparator is satisfied, then the whole version range will be satisfied. For example, a version range of 2.0.0||>3.1.4 will be satisfied if either the version is less than 2.0.0 or it is greater than 3.1.4.

Pre-release tags

A version can also have a pre-release tag(e.g 3.1.4-beta.2). If you have a comparator that includes a version that has a pre-release tag, it will only match versions that have the same major.minor.patch version.

For instance, the range >=3.1.4-beta.2 will match 3.1.4-beta.2 or 3.1.4-beta.12, but will not match 3.1.5-beta.1 even though 3.1.5-beta is technically "greater than or equal to" (>=) the 3.1.4-beta.2 version.

Advanced version ranges

Hyphen Ranges

A hyphen range (e.g 3.0.0-4.1.5) specify an inclusive set. If you leave part of the version out (e.g 0.4 or 2) they will be filled with zeroes.

X-Ranges

You can use any of X, x, or * to leave part or all of a version as unspecified.

If you omit a part of a version, it is assumed that it is an x-range.

Tilde Ranges

When you use ~ with specified minor version, it permits you to patch changes. Use of ~ with just the major specified version allows minor changes.

Caret Ranges

This permits you to make changes that do not modify the first non-zero digit in the version, it could either be the 2 in 2.1.4 or the 3 in 0.3.2.

If you leave a part of the version out, the missing parts will be filled in with zeroes. However, this still allows for that value to be changed.

Previous: Understanding dependencies in Yarn packages.
Next: Selective Dependency Resolutions in Yarn.