If you are already using npm cli to manage package/product version, this article might not be for you.
It may seem very obvious, to use npm cli to maintain package version(s) however in reality its totally different. I have seen projects where versioning is handled manually.
What is version?
When we release a package we need to version it. Versioning a release could also be swapped with term tagging.
When we create a version, we are actually pointing a git commit id to human readable alphanumeric string. In below example we can see how v16.8.3
is linked to commit id 29b7b77
What is semantic version?
A release could fall in any of below categories
- Major release: Non backward compatible changes
- Minor release: Backward compatible with new feature
- Patch release: Bug fix release with no new feature
For example, if current package version is 1.0.0
- patch release version would be 1.0.1
- minor release version would be 1.1.0
- and, major release version would be 2.0.0
Now, you can manually update the version in package.json and create new tag on current commit id however this is not what we want. We want some automation in this process.
Let's, do it!!
Automate semantic version with npm cli?
To demonstrate automation process, I am going to quickly create a new package and initialise repository on my local drive
mkdir semver && cd $_ && npm init -y && git init
Next, lets create a javascript file with single console.log
statement just to visualize changes in git log
echo "console.log(\`index file -> v1.0.0\`)" > index.js
Also, lets commit changes to local repository
git add .
git commit -m "initial commit"
If we open package.json we can see, right now the version is set to 1.0.0
{
"name": "semver",
"version": "1.0.0",
// skipped rest of lines
}
Lets begin by creating patch release
To make it more realistic lets change the console.log
statement to print index file -> v1.0.1
Open your favourite editor and make those changes - finally the contents of index.js
file should be
console.log(`index file -> v1.0.1`)
Also, do not forget to commit you changes.
git add .
git commit -m "fixed issue with console statement"
To create patch release we just need to type npm version patch
in terminal
npm version patch
v1.0.1
That's it - npm automatically updated the package.json and created new tag v1.0.1
.
To verify, open package.json in editor and you should see new version
{
"name": "semver",
"version": "1.0.1",
// skipped rest of lines
}
Similarly, to verify if a new tag v1.0.1
was created we can type git tag
in terminal
git tag
//output
v1.0.1
How cool was that!!!
Now, lets create minor release
Again, make some backward compatible changes in index.js and commit those changes
// contents of index.js after changes
console.log(`index file -> v1.1.0`)
// commit changes
git add .
git commit -m "updated minor version in logs"
To make minor version we just modify last portion of command as follows
npm version minor
//output
v1.1.0
Cool!!! you can again verify the updated version in package.json and new tag that was created using git tag
command
Finally, lets create major release
Lets replace contents of index.js with below contents and commit changes
// contents of index.js after changes
console.log(`Hello`, process.env.USER)
// commit changes
git add .
git commit -m "replaced console message with new one"
To bump the major version we update last command as follows
npm version major
// we should see below output
v2.0.0
Finally, if we run git tag
command on terminal, we should see all tags that we created above
git tag
// output
v1.0.1
v1.1.0
v2.0.0
You can type npm version --help
in terminal to see all available options or, read further on official page npm cli
I hope you liked this article!!
Top comments (1)
This will work if you are working alone on the project, but once the more people start contributing, and you have several branches with their own commits and version changes. We had this problem at my office before and then decided to bump the project version only on prod releases instead on each merge/pull request.
Also, forgive for my nitpicking but running
npm patch/minor/major
every time you commit something is not automatization.