In the previous lesson you installed dotenv and npm wrote ^17.2.1 in the manifest, not 17.2.1. That caret is a decision with enormous consequences: it means your project is not asking for a version, it is asking for a range, and the specific version that ends up installed depends on what dotenv's author has published by the day someone runs npm install.

That is either a time bomb or an extraordinary convenience, depending on how you understand it. Without package-lock.json, two people on the same team can install the same package.json on different days and end up with different dependency trees. With it, the install is reproducible down to the last byte.

This lesson has two halves that explain each other: the versioning system that promises compatibility and the file that makes that promise unnecessary.

1. SemVer: MAJOR.MINOR.PATCH and the implicit contract
2. Pre-release versions and their precedence order
3. The range table, with the row almost nobody knows
4. What each range installs today and six months from now
5. package-lock.json: what it contains exactly
6. npm ci versus npm install
7. Lock conflicts in git
8. npm dedupe and --save-exact
9. The minor update that breaks things
10. From 0.1.0 to 1.0.0: versioning Escena Viva

Semantic versioning (semver.org) is a convention that turns three numbers into a verifiable promise:

The rules for when each number goes up:

When a number goes up, everything to its right resets to zero: from 17.2.1, a minor bump gives 17.3.0, and a major bump gives 18.0.0.

The implicit contract is the part people forget. Publishing 17.3.0 instead of 18.0.0 is not an aesthetic preference: it is a statement to thousands of projects that they can upgrade without reviewing their code. And since 90% of those projects have ^17.2.1 written down, that minor version will enter their installs automatically. If you lied, their builds break tomorrow without them having changed a line.

That is why semver is, before it is a technical rule, a matter of responsibility. And it is also why you cannot fully trust it: it is a convention, not something the registry verifies. What does get verified is the lockfile, and that is why the two halves of this lesson belong together.

Before a stable version, test versions are published with a hyphen:

The precedence rules, as defined by the specification: a version with a pre-release tag is always lower than the same version without one (1.0.0-rc.1 < 1.0.0, because it is a rehearsal for that version, not a later one); identifiers are compared left to right; numeric ones as numbers and alphanumeric ones alphabetically; a number is always lower than text (1.0.0-1 < 1.0.0-alpha); and when everything above ties, whoever has more identifiers wins (1.0.0-alpha < 1.0.0-alpha.1).

A complete ordered series:

Notice beta.2 < beta.11: because the identifier is numeric it is compared as a number, not as text. If it were compared as text, 11 would come before 2.

The most important part day to day: pre-release versions never enter a normal range. If your manifest says ^1.0.0 and 2.0.0-beta.1 is published, npm will not install it. To receive them you have to ask explicitly (npm install package@beta) or write a range that includes them. It is a deliberate protection, and it is the right one.

This is the table to know by heart. Suppose the latest published version is 1.9.2 and that 2.0.0 and 1.2.9 also exist.

The short way to remember the two important ones: ~ lets the last number rise; ^ lets the last non-zero-from-the-left one rise.

Here is the detail that produces unpleasant surprises. The caret is defined as "do not change the first non-zero number", and that gives different behavior when the major is 0:

The logic is sound: in 0.x the library declares that its API is still moving, so semver treats every minor version as potentially incompatible. The practical consequence is surprising though: an npm update moves nothing in a 0.x package apart from patches. If you expected to go from 0.2.9 to 0.4.0 automatically, it will not happen; you have to change the range by hand.

And the corollary for when you publish: while you are on 0.x you promise nothing, and whoever uses you knows it. That is precisely why Escena Viva started at 0.1.0 and not at 1.0.0.

The thought experiment that clarifies the problem. Today, with [email protected] as the latest published version:

All three agree. Now fast-forward six months: 17.2.5, 17.6.0 and 18.0.0 have been published. Someone clones the repository, runs npm install without having touched package.json and gets:

Three people with the same repository and three different trees. That is exactly the problem the lockfile solves.

Compare the recommended range according to the project's role:

It is generated on its own as soon as there is any dependency. Here is a real fragment, trimmed:

Field by field:

The integrity field is what makes this security and not just convenience. On every install npm downloads the tarball, computes its SHA-512 and compares it with the recorded one. If they do not match —because someone tampered with the registry, because a mirror served something else, because a cache got corrupted— the install fails. That is cryptographic integrity across your whole dependency tree, for free.

Hence the rule that is not up for negotiation:

package-lock.json DOES go into version control. Always.

The reasons: reproducibility (your laptop, your teammate's, CI and the server all install the same thing, today and a year from now); security, because the hashes travel with the repository; debugging, since git log package-lock.json tells you which version changed and when, which is usually the answer to "this worked last week"; and auditing, because npm audit analyzes the lock's exact tree and not an approximation.

The only real exception is a published library: its lock does not affect whoever installs it, because every project resolves its own tree. Even so, many libraries commit it so their own tests are reproducible. Escena Viva is an application: it commits it without discussion.

And the flip side: the lock is never edited by hand. It is a generated file. You change it by running npm commands.

With the lock on the table, the module's key comparison:

The decisive row is the fourth. If someone edits package.json by hand —bumps a range, adds a dependency— and does not run npm install, the lock is left out of sync. In that state, npm install fixes it silently; npm ci digs in its heels:

That error is good news: CI has detected that the repository is inconsistent before anything gets deployed. Hence the module's operational rule, which we will reuse in Module 11:

• On your machine: npm install, npm install <package>, npm update. They modify the lock, and that change is committed to git as part of the work.
• In CI, Docker and production: npm ci (with --omit=dev in production). Never npm install.

It is inevitable: two branches add different dependencies, they get merged, and git presents a conflict in a three-thousand-line generated file.

What you do not do: open the file and pick by hand between <<<<<<< markers. The lock is a coherent graph; resolving it piecemeal produces an inconsistent tree that "almost" works.

What you do: discard the file and regenerate it from the manifests, which are human-readable.

An equally valid alternative: delete the lock and run npm install. It is more aggressive —it can raise versions inside the ranges, since everything is resolved again— so the first option is preferable when you want to touch as little as possible.

A hygiene tip: a new dependency deserves its own commit, with package.json and package-lock.json together and nothing else. That way the conflict, if it comes, is tiny, and code review can really look at what got in (05-06).

npm dedupe reorganizes the tree to share as many copies as possible. After several successive installs it is easy to end up with duplicates that are no longer needed:

If both ranges accept 1.5.0, npm dedupe lifts a single copy to the root and deletes the nested ones. Less disk, less audit surface, and goodbye to the instanceof problem between different copies of the same class.

It modifies node_modules and the lock, so you run it in development and commit the result. Never in production.

--save-exact (alias -E) saves the version without the ^:

Or as a project policy, in the .npmrc from 05-01:

Is it worth it? The honest answer is almost never in an application with a lock, because the lock already pins the real version and the range only expresses which update policy you accept. With ^ plus a lock, npm ci is exactly as deterministic.

Pinning exact versions does pay off in three specific cases:

The cost is real: with exact versions, npm update stops being useful and upgrading means touching the manifest package by package. On a large project that gets delegated to Dependabot or Renovate (05-06).

The scenario that justifies everything above. On a Tuesday, Escena Viva's CI fails. Nobody has touched the code since Friday.

The cause: [email protected] was published on Monday. Your manifest says ^17.2.1, CI was not using a lock and npm install brought in the new version. A behavior change the author considered minor —how it interprets quotes in .env values, for example— breaks one of your tests.

What to take from that story:

^ is not a guarantee, it is an expectation. It trusts a third party to classify their own change correctly. Most of them do; getting it wrong is easy, because nobody knows every use of their own library. A change the author sees as a fix may be the very behavior you depended on.

The lock turns that expectation into a fact. With package-lock.json in the repository and npm ci in CI, Tuesday would have installed 17.2.1, just like Friday. The new version would come in the day someone runs npm update deliberately, sees the change in the lock's diff and passes the tests before merging.

The difference is not that the failure disappears: it is who controls when it happens. Without a lock, it ambushes you on a Tuesday morning in production. With a lock, it happens on a branch, with an owner and with tests in front of it.

That is why the correct order for upgrading is always the same:

To jump a major version, the process is different and not automatable: read the release notes, change the range by hand, adapt the code and test. A separate branch, always.

Escena Viva was born at 0.1.0 because its API was moving. With Module 4 finished, it has a public, stable HTTP API —GET /api/events, POST /orders—, a settled domain and a client (the front end in public/) that depends on it. It is time for the jump.

npm version does three things, not one: it changes version in package.json and in package-lock.json, it creates a git commit with that change (with 1.0.0 as the default message) and it creates an annotated git tag, v1.0.0, which is the only thing it prints to the screen.

It also accepts bumps by name, which is how it is used day to day:

If you do not want the commit or the tag —because your publishing flow generates them another way— there is --no-git-tag-version.

What the jump to 1.0.0 really means in Escena Viva:

Concretely, from now on: removing a field from the GET /api/events response is major; adding a new field is minor; changing the meaning of an error.appCode in the Module 4 error table is major; fixing a badly computed capacity calculation is patch.

That commitment is the same one you have been demanding from dotenv throughout this lesson. Here you switch sides of the table, and that is why the module continues towards publishing.

• Adding package-lock.json to .gitignore. It is the most expensive mistake in the module: it destroys reproducibility. What gets ignored is node_modules/, never the lock.
• Resolving lock conflicts by hand. It produces incoherent trees that fail in strange ways. Regenerate it with npm install.
• Using npm install in CI. It can modify the lock during the build and deploy something different from what you tested. npm ci, always.
• Expecting npm update to bump a major version. It never does, by design. Nor minors in 0.x packages, because of the ^0.x.y rule.
• Publishing 1.0.0 without meaning to promise stability. If your API is still moving, stay on 0.x: it is honest information for whoever uses you.
• Putting * or latest as a range. Any major version gets in without warning. There is no case where it pays off.
• Tip: review the lock's diff. In a code review, a lock that changes while package.json does not deserves a question.
• Tip: npm view <package> versions --json lists every published version. Useful for seeing the release cadence before adopting a dependency.

Exercise 1. Resolve ranges by hand. A package has these versions published: 0.9.0, 1.0.0, 1.2.0, 1.2.5, 1.9.0, 2.0.0-beta.1, 2.0.0, 2.1.0. Say what each of these ranges would install: ^1.2.0, ~1.2.0, 1.2.x, >=1.0.0 <2, ^2.0.0, *, 1.2.0 - 1.9.0. Then repeat the exercise assuming the published versions are 0.1.0, 0.2.0, 0.2.5, 0.3.0 and the range is ^0.2.0.

Exercise 2. See the lock in action. In Escena Viva, run npm ls dotenv and note the version. Open package-lock.json and find its version, resolved and integrity. Now delete node_modules, run npm ci and check that the version is identical. Then edit package.json changing the range to ^17.0.0 without running npm install and launch npm ci. Explain what happens and why it is the desirable behavior.

Exercise 3. Version Escena Viva. Run npm version 1.0.0 with a clean git tree. Check with git log -1 and git tag exactly what it created. Then decide which kind of bump (patch, minor or major) each change calls for: (a) adding the accessibleVenue field to the GET /api/events response; (b) fixing the available-seats calculation, which was subtracting wrongly; (c) renaming priceCents to amountCents in the API response; (d) changing LOW_CAPACITY_THRESHOLD from 20 to 15; (e) requiring Node 26 in engines.

Solution 1. First part:

Second part: ^0.2.0 installs 0.2.5, not 0.3.0. That is the ^0.x.y rule: with the major at zero, the caret protects the minor number too, because 0.3.0 is considered potentially incompatible. This is the answer most people get wrong.

Solution 2. After npm ci, npm ls dotenv shows exactly the same version: the lock rules, not the range.

When you change the range to ^17.0.0 without installing, npm ci fails:

It is desirable because being out of sync is a real repository error, not a detail. Someone touched the manifest without regenerating the lock, so nobody knows which tree was meant to be deployed. npm install would paper over it silently and deploy a resolution nobody has reviewed; npm ci stops the deployment and forces it to be fixed on a branch. The fix is running npm install and committing the resulting lock.

Solution 3. npm version 1.0.0 produces:

Classification of the changes:

Case (d) is the interesting one: the answer depends on whether that constant is part of the public contract. That ambiguity is exactly the hard part of semver, and the reason a clear CHANGELOG is worth as much as the numbers.

You can now read the language the whole ecosystem uses to communicate. SemVer turns three numbers into a promise: PATCH fixes, MINOR adds without breaking, MAJOR breaks. Pre-release versions are always lower than their stable counterpart and do not enter normal ranges. And from the range table you take away two shapes: ~ lets the last number rise, ^ the last non-zero-from-the-left one —hence ^0.2.3 accepting patches only, the rule almost nobody knows and the one that explains why npm update sometimes seems to do nothing.

But the underlying lesson is that ^ is an expectation, not a guarantee: it depends on a third party classifying their own change correctly. What turns that expectation into a fact is package-lock.json, with its exact tree, its resolved versions, its URLs and above all its SHA-512 integrity, which makes the install fail if the downloaded content is not byte for byte what was recorded. That is why it always goes into the repository, why it is never edited by hand, and why its git conflicts are resolved by regenerating it rather than picking between markers.

From that comes the operational rule that will stay with you to the end of the course: npm install on your machine —it modifies the lock, and that change gets committed and reviewed— and npm ci in CI, in Docker and in production, which requires the lock, honors it to the letter, deletes node_modules and fails if the manifest and the lock do not match. That failure is good news: it stops an inconsistent deployment before it reaches anyone.

Escena Viva is now 1.0.0, with its v1.0.0 git tag created by npm version, and that number is a commitment: from today on, removing a field from the API or changing the meaning of an error.appCode forces a bump to 2.0.0.

In the next lesson, npm Scripts and Project Automation, we fill the manifest's last gap. The scripts field is about to become the project's single interface —npm start, npm run dev, npm run report, npm test— so nobody has to read the README to guess a command. And along the way you will discover why a tool you never installed globally works anyway: the PATH extended with node_modules/.bin.