This article part of a series on Mastering npm in the Enterprise, also available as a chapter in our free, downloadable eBook

Managing npm package versions across development teams is way more complicated than you’d think. If you’re relying on simple npm tags like latest or next, you may be running into issues like dependency conflicts or unexpected breakages. At worst your development may end up in chaos, especially in CI/CD workflows where automated deployments make it easy for unstable code to slip into production. 

A much better approach to versioning is using Semantic Versioning (SemVer) pre-release labels and repackaging your pre-release versions. Instead of relying on npm tags, teams can adopt a workflow that includes designated pre-release versions (such as alpha, beta, and release candidates) and automate release processes to make sure only stable versions are deployed.

In this article, I’ll walk you through implementing an npm versioning strategy tailored for team development in CI/CD environments. We’ll look at managing version flows without custom npm tags by using SemVer pre-release labels and repackaging pre-release packages into stable releases. 

Challenges of Versioning and Why You Should Avoid Custom Tags

A big challenge of managing npm versioning across your development teams is the risk of using versions with breaking or unstable changes. Using npm’s custom tags like “alpha” or “beta” to get around this doesn’t really help. In fact, the confusion caused by using them often makes things worse.  

Custom tags are managed server-side and are not tied to specific versions. They can be easily reassigned, which usually leads to version conflicts and dependency confusion. Let’s say a developer tags a pre-release version of a package as “alpha”. Later, another dev uses the same tag for a different pre-release version. The result? The original tag gets overwritten, causing the second version to propagate through the development environment, and ends up breaking it. 

This is why you need a more controlled approach to versioning. Instead of relying on custom tags, I recommend using npm’s Semantic Versioning Version 2 (SemVer2) to indicate stability and readiness for production, helping you avoid the typical problems of poorly managed versioning. 

Using Semantic Versioning and Pre-release Labels 

Semantic Versioning (SemVer) is a widely adopted standard that indicates the nature of changes in software versions using a clear structure: 

• Major versions introduce breaking changes. (e.g 1.0.0) 
• Minor versions add features in a backward-compatible way. (e.g 1.1.0) 
• Patch versions fix bugs in a backward-compatible manner. (e.g 1.1.1) 

npm supports Semantic Versioning 2.0 (SemVer2), which includes pre-release labels for even greater control. Pre-release labels added to the package name (like myPackage-1.2.0-alpha.1) give you a structured, immutable way to track development stages, avoiding the confusion that comes with using generic custom tags.

Let’s say you have two developers working on pre-releases for the same package. Instead of both using the ambiguous “alpha” tag, they follow SemVer2 and use unique labels like 1.2.0-alpha.1 and 1.2.0-alpha.2. This will prevent version overwrites and maintain a clear history —unlike custom tags like alpha, which can be accidentally overwritten. 

That said, pre-release labels are just part of the process. The real game-changer comes next —repackaging the pre-release into a stable version to ensure it’s fully ready for production. 

Repackaging for Production-Ready Releases in CI/CD Pipelines 

Repackaging involves converting a pre-release version into a stable version once all testing is complete. Doing this makes sure the version is stable and safe for production. When using a CI/CD tool like Buildmaster, you can enforce version stability by blocking pre-releases from being deployed to production environments. Once a version passes all tests, the tool automatically repackages it as stable and deploys it. 

Imagine it like this; a development team releases a new feature update as 1.2.0-alpha.1 for internal testing, progresses it through 1.2.0-beta.1 for broader testing, and then labels it as 1.2.0-rc.1 (release candidate) for final vetting. Once the version reaches 1.2.0-rc.1 and passes all final checks, it is repackaged as 1.2.0 for stable release 

By repackaging pre-releases, you can prevent the headaches you might get with unexpected updates and dependency issues, promoting issue-free deployments and a more reliable production environment. 

npm Versioning Done Right 

Managing npm versions across teams is challenging, and using custom npm tags often does more harm than good. They increase the risk of unstable code reaching production, leading to unnecessary downtime or system failures. 

Adopting SemVer2 with pre-release labels and implementing repackaging in CI/CD pipelines can significantly reduce these risks. Structured pre-release labels provide clarity and immutability, while repackaging makes sure only stable, thoroughly tested versions are deployed to production. 

Phew, that’s a lot to take in for today! I recommend keeping this info handy for future reference. I’ve compiled all this and more into an eBook “npm in the Enterprise“. You’ll not only learn more about npm versioning but also about dependencies, scoping, vulnerabilities, licenses, auditing and much more! Download your free copy today!