Semantic Versioning in npm

Serhii Shramko

Serhii Shramko /

3 min read • --- views

Let’s talk about version numbers in your package.json. You’ve probably seen versions like 1.2.3 or ^4.5.0—but what do they actually mean?

but it works on *my* machine joke

SemVer: The Three-Number System That Keeps Everyone Sane

Semantic Versioning (SemVer) is just a fancy way of saying:
“Hey, let’s use version numbers to tell people what kind of changes we made.”

Versions look like x.y.z:

  • Major (x): Big changes that might break your code. Example: Removing a feature your app relies on.
  • Minor (y): New stuff that won’t wreck existing code. Example: Adding a cool new function.
  • Patch (z): Quiet fixes for bugs or security holes. Example: Fixing a crash when you type null.

Think of it like home renovations:

  • Major = Tearing down a wall (big impact).
  • Minor = Adding a new room (no harm done).
  • Patch = Fixing a leaky faucet (everyone’s happy).

Why Should You Care?

Because npm uses these numbers to decide which updates are safe to install automatically. If everyone follows SemVer, your app won’t suddenly break when you run npm update.

The Secret Symbols in Your package.json

Those weird characters like ^ and ~ in your dependencies? They’re just rules for npm. Here’s what they really mean:

  • ^1.2.3 = “New features and fixes are okay, but don’t change anything big!”
    (Updates to 1.3.0 or 1.2.4 are fine. Won’t jump to 2.0.0.)

  • ~1.2.3 = “Only tiny fixes, please.”
    (Updates to 1.2.4 are okay. Won’t go to 1.3.0.)

  • > or >= = “Give me anything newer than this.”

  • < or <= = “Nothing newer than this, thanks.”

  • 1.2.3 - 1.5.0 = “I’ll take any version between these two.”

  • || = “Either version A or version B works.”

No symbol? Example: "lodash": "4.17.21" means “Only this exact version. Don’t change a thing!”

Real-World Tips for Humans

  1. Start with ^ for most dependencies. It’s the safest way to get bug fixes and new features without surprises.
  2. Use exact versions for critical packages (like React or Vue) where unexpected changes could ruin your day.
  3. Check npm outdated weekly to see which packages have updates. It’s like a to-do list for your app’s health.
  4. Commit package-lock.json to avoid “but it works on my machine” moments. This file locks down every tiny detail.
but it works on *my* machine joke

When Things Go Sideways

  • Broke after an update? Check if a major version sneaked in. Temporarily pin the version
    "package": "1.2.3" until you fix things.
  • Confused by symbols? Use semver.npmjs.com to test what versions your rules allow.

Quick Cheat Sheet

SymbolWhat It Means
^1.2.3“Keep me up to date, but no big changes!”
~1.2.3“Only bug fixes, please.”
1.2.x“Any patch version for 1.2.”

Wrapping Up

SemVer isn’t about memorizing rules—it’s about communicating changes clearly. Use ^ for flexibility, ~ for caution, and exact versions when stability matters.
And always, always check your package-lock.json into Git.

Try this now:

npm outdated

See what updates are waiting? Update one with npm update package-name and see if your app still works. You’ve got this! 🛠️

P.S. Sharing is caring. Forward this to a teammate who still edits package.json versions by hand. 😉

Share it: