## **Overview**

[NPM](https://www.npmjs.com/) stands for Node Package Manager. It is the largest package registry in the world. It contains hundreds of thousands of packages uploaded to it.

NPM uses SemVer by default. It allows only [SemVer](https://www.buzzchart.info/post/semantic-versioning) syntax in the package version declaration. SemVer is very powerful and simple at the same time. NPM packages using SemVer enhanced syntax to declare package dependencies. This concept makes the dependency declaration very powerful and flexible. At the other hand it can be complex to comprehend how dependencies are resolved.

## **Dependency declaration**

NPM package can define dependency as a strict version (**`1.2.3`**) or a range of versions (**`1.2.x`**, which is resolved to **`1.2.0`**, **`1.2.1`**, **`1.2.3`**, **`1.2.4`**). You can define a range for a newest patch versions or newest minor version, [or other crazy definitions are available](https://docs.npmjs.com/about-semantic-versioning). Using a version range definition, you have multiple versions applicable for you your dependencies or transitive dependencies. NPM will resolve a tree of dependencies according to the version declaration in the dependencies and its dependencies. Dependencies are evolving and releasing new versions constantly. Depending on the point in time, different dependencies will be resolved. How to know what dependencies are resolved? How to lock the dependencies and have a reproducible build? **`package-lock.json`** solves this problem.

## **package-lock.json**

**`package-lock.json`** is a file ([npm reference](https://docs.npmjs.com/cli/v10/configuring-npm/package-lock-json)), generated in the root of a workspace/monorepo or in the package root. It contains all information about the used dependencies used in the project. It captures the concrete versions at the time it was created. This allows to:

- have reproducible build

- prevent npm from resolving the tree of dependencies

- understand/introspect what is used in the project and track the evolution of dependencies

## **Same dependency, different version**

Different dependency branches may have different versions. For example one branch using **`lodash@14.16.x`**, other brach uses **`lodash@14.17.x`**. This means that project will contain different versions of the **`lodash`**. This gives lots of flexibility in the dependency management. Because npm solves the compatibility problems and choses the right version for you. It comes with a cost of:

- increased bundle size

- complexity in observing the whole picture of dependencies

- security vulnerabilities might not be fixed withing the defined ranges.

## **Conflicts and overrides**

Conflicts can occur for an incorrect dependency declaration. Consider the case when you need to have one library in the runtime(**`react`** or components library for example). And for some reason you will have 2 libraries in the runtime which will cause discrepancies in the JS or CSS evaluation.

Another reason already mentioned in the previous section. Security vulnerability fix. For example we have a declared version of **`lodash@14.17.20`**. **`lodash@14.17.21`** contains critical security fix, but you have no control over transitive dependency declaration.

The melanism to solve this problem is npm "[overrides](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#overrides)".

> Overrides provide a way to replace a package in your dependency tree with another version, or another package entirely. These changes can be scoped as specific or as vague as desired.

Versioning in NPM

It was introduced in 2009 by Tom Preston-Werner, co-founder of a GitHub. It was designed to provide a clear and universal way to mark software updates. There was a convention, which was almost the same as semver. But the word almost is not good enough, when you want to know what exactly the impact of changes is.

Semantic versioning is a convention, how to set versions to your code artifacts. It is called semantic, because it communicates the changes in the version, comparing to the previous version. Managing code dependency versions can become challenging if you are not aware of changes present in new version of artifact.

- Imagine you have 100 dependencies. How to know what dependencies can I update? Reading the release notes will be time consuming for the 100 dependencies.

- What if you need bug or security fix. Does new release contains only this bug fix or something else that can break an API?

- What if I need this new feature, but also I do not want to migrate?

- Is this version stable?

- How to add canary version build metadata into version?

All of these questions together with many others can be answered just looking at the version. SemVer has an answer to all these questions. The convention is very simple:

- X.Y.Z are the mandatory parts of version, where each letter i a numerical value

- X - called major version, updating it means that breaking changes are present in the API

- Y - called minor version, updating it means that new feature is added to the API

- Z - called patch version, updating it means that no API changes are done, only bug/security/performance fixes

- "+" indicates the build metadata (1.2.3+20240417)

- "-" indicates the prerelease version (1.2.3-canary.1)

## **Who is using SemVer?**

- SemVer is enforced in the npm(Node Package Manager) repository. Your version myst syntactically comply with the SemVer rules. It is central part of managing versions in the JavaScript world. Though you cannot automate the validation of breaking changes npm repository. This is the [recommendation of npm ath their page](https://docs.npmjs.com/about-semantic-versioning).

- RubyGems, package manager for ruby libraries is also a broadly adopted convention of managing artifact versions. The official documentation [describes semver as a pattern](https://guides.rubygems.org/patterns/) you should name your version.

- Docker Hub, repository for Docker images does nor fully support SemVer, though the community want to adopt the semver. The "+" symbol is not supported in the Docker Hub and maintainer is not willing to add support for it. This is the [GitHub issue maintainers comment](https://github.com/distribution/distribution/pull/1202#issuecomment-160761964), on the SemVer and "+" build metadata in the tag.

- Go is also embracing SemVer for its packages and [describes how to do it](https://go.dev/doc/modules/version-numbers).

Semantic Versioning solves multiple problems in the dependency management area. It is widely adopted, because it is easy to use and the version communicates changes being made. For some software projects this is go-to versioning strategy. Lots of tooling supports semver to manage package releases. It helps to remove version-lock problem, when you need to release a package, because your dependency changed and you do not know the impact of changes. Sem

## **Other versioning systems**

Though this versioning system is not the only one. There is also:

- Calendar Versioning (CalVer), it includes year, month and possibly day when it was released (2024.01, 2024.02).

- Sequential versioning - version-1, version-2...

- Release Train Model - where you have planned release schedule and you are naming the release artifact version based on a release number, rather than on a feature completion or changes in the software. Version name can combine CalVer, Sequential versioning or other versioning models (24.1, 24.2).

There are more versioning systems used in the software world. You need to chose the right tool for the job. And in many cases the semver is a right tool.