A Complete Guide to Versioning in package.json

If you’ve worked on a project using package.json, you’ve probably seen a version like this:

{
  "name": "my-app",
  "version": "1.0.0"
}

This follows Semantic Versioning (SemVer), which helps developers manage updates without breaking things. But what do these numbers mean, and when should you change them?

Understanding Versioning (SemVer)

The version format is: MAJOR.MINOR.PATCH (e.g., 1.0.0)

🔹 MAJOR (1.0.0 → 2.0.0) → Breaking changes, major redesigns, or API changes.

🔹 MINOR (1.0.0 → 1.1.0) → New features added, but everything still works as before.

🔹 PATCH (1.0.0 → 1.0.1) → Bug fixes or small improvements without adding new features.

Example:

{
  "version": "2.3.5"
}

• 2 → Major version (big breaking change).
• 3 → Minor version (new features added).
• 5 → Patch version (small fixes, no breaking changes).

How to Change the Version in package.json?

📌 Manually update it in package.json:

{
  "name": "my-app",
  "version": "1.1.0"
}

📌 Use npm commands:

npm version major  # 1.0.0 → 2.0.0
npm version minor  # 1.0.0 → 1.1.0
npm version patch  # 1.0.0 → 1.0.1

This updates package.json and creates a Git tag automatically.

How This Relates to Git?

When you update the version, tag it in Git to track releases:

git tag v1.1.0
git push origin v1.1.0

This helps roll back to a stable version if needed.

Additional Versioning Tips

What is ^ and ~ in dependencies?

When you see:

"dependencies": {
  "react": "^18.2.0"
}

• ^18.2.0 → Allows minor updates (e.g., 18.3.0 but not 19.0.0).
• ~18.2.0 → Allows patch updates (e.g., 18.2.5 but not 18.3.0).

What is 0.x.x?

If your project is in early development, keep the version below 1.0.0.

• 0.1.0 → First minor release.
• 0.1.1 → Small bug fix.
• 0.2.0 → New features added.
• 1.0.0 → Stable version, ready for production.

Why Versioning Matters?

• ✅ Prevents breaking your project when updating packages.
• ✅ Helps teams track changes and improvements.
• ✅ Keeps your project stable while allowing controlled updates.

Next time you update a package or your project, use versioning wisely!

#SoftwareDevelopment #Versioning #npm #Git #WebDevelopment