Versions and lockfiles

Your project depends on someone else's code, and that code keeps changing. Every change is a small gamble: does the new release fix a bug you had, or break something you relied on? Without a convention you would have to read the changelog of every package on every update, which nobody does.

Semantic versioning is the convention that turns the version number into a promise about that risk. The npm registry documents it, most packages follow it, and once you can read it you can tell at a glance whether an upgrade is a routine bump or something to schedule an afternoon for.

The promise is only as good as its author's discipline - a package can break you in a patch release by accident. Semver is a strong convention with human beings behind it, not a guarantee enforced by machinery. Which is precisely why the second half of this lesson exists.

A version is three numbers separated by dots: 4.1.0 is major 4, minor 1, patch 0. Each position answers a different question about what changed.

A patch release increments the last digit and means backwards-compatible bug fixes: code that worked before still works. A minor release increments the middle digit and resets the last to zero, and means backwards-compatible new features: things were added, nothing you were using was taken away. A major release increments the first digit and resets the other two, and means breaking changes: something you might be relying on has changed or gone.

So 4.1.0 to 4.1.3 should be invisible to you. 4.1.0 to 4.4.0 should be safe but brings new capability. 4.1.0 to 5.0.0 is the one that needs reading and testing. Nothing about the size of the number tells you about quality or maturity - a package at 47.0.0 has simply broken compatibility 47 times, which may just mean it is honest about it.

The versions in a package.json are usually not exact. "date-fns": "^4.1.0" is a range, and it means "at least 4.1.0, and any later release that does not change the major number" - so 4.9.2 is allowed in, 5.0.0 is not. The caret is npm's default when you install something, and it is a bet on the author keeping the semver promise for minor and patch releases.

The tilde is stricter. "~4.1.0" allows patch releases only: 4.1.9 yes, 4.2.0 no. Use it when you want bug fixes without new surface area. An exact "4.1.0" with no symbol allows nothing at all - the strictest choice, and occasionally the right one for a dependency that has burned you.

There is one edge case that catches everyone, and it is not an exception so much as the rule stated properly. The caret allows changes that do not modify the left-most non-zero number. Above 1.0.0 that number is the major, so ^4.1.0 permits minor and patch updates. Below 1.0.0 the left-most non-zero number is the minor: ^0.2.5 permits 0.2.x but NOT 0.3.0, because a 0.x package is announcing that its shape is still moving and a minor bump may well break you.

Sit with what a range implies. Your package.json says ^4.1.0. You installed in March and got 4.1.0. A colleague clones the repository in June, runs npm install, and gets 4.6.2 - also inside the range, also correct, and not the same code you have been testing against. Neither of you did anything wrong, and yet you are now running different programs.

Multiply that by every package your packages depend on, and "works on my machine" stops being a joke and becomes an accurate description of the situation. The ranges are doing exactly what you asked; the problem is that what you asked for was a set of acceptable versions, not a specific program.

The fix is to record the answer as well as the question. package.json holds the question - which versions would be acceptable. A second file holds the answer - which versions were actually chosen last time, all the way down the tree.

npm writes package-lock.json whenever an install changes node_modules or package.json. Its own documentation describes it as a description of the exact tree that was generated, so that later installs can produce an identical tree regardless of what has been published since.

That is why it is committed to source control rather than ignored. The npm docs give the reasons plainly: teammates, deployments and continuous integration all install exactly the same dependencies; you can travel back to a previous state of node_modules without committing the folder itself; and changes to the tree show up as a readable diff, so a review can see that a dependency changed.

It also records exactly where each package came from and an integrity hash for its contents, which is what turns "the same version number" into "the same bytes". A version number can be re-published; a hash cannot be argued with.

npm install is the working command. It reads package.json, may resolve a range to something newer, updates node_modules and writes the lockfile to match. Use it when you are adding, removing or deliberately updating a dependency.

npm ci is the reproducing command. It requires a lockfile to exist, removes node_modules first if it is there, and installs exactly what the lockfile says. If the lockfile and package.json disagree, it stops with an error instead of quietly resolving the difference. It also cannot install a single package - it is all or nothing, by design.

The rule that follows: continuous integration, deployments and any "why does this only fail on the server" investigation want npm ci, because it is the only one of the two that promises you the same tree twice. Day-to-day development wants npm install. If npm ci fails complaining that the two files are out of sync, the fix is to run npm install locally and commit the updated lockfile - not to delete it.

Deleting package-lock.json to fix an install problem. This is the single most expensive reflex in this lesson. It does often clear the immediate error - by throwing away the record of every version that was known to work, and re-resolving the entire tree to whatever is newest today. If you must reset, delete node_modules and run npm ci, which keeps the record.

Resolving a lockfile merge conflict by hand. It is a generated file, and hand-editing it produces a tree that never existed anywhere. Take one side, run npm install, and commit what npm writes.

Reading a caret as a safety guarantee. It is a promise made by a human being about their own future releases. Most keep it; some do not. That is not an argument for pinning everything to exact versions - you would never get a security fix - it is an argument for the lockfile plus tests you trust, which is the subject of the next module.

major.minor.patch: breaking, additive, fixed. A caret allows anything that does not change the left-most non-zero number, so ^4.1.0 permits 4.x and ^0.2.5 permits 0.2.x only; a tilde allows patch releases; a bare number allows nothing. Ranges mean two machines can legitimately install different code, so the lockfile records the exact tree that was chosen, with integrity hashes, and is committed. npm install may update that record; npm ci reproduces it exactly and refuses to paper over a mismatch.