What a lockfile is, and why it is not a formality

Every JavaScript project has one of these files, almost nobody reads them, and everybody deletes them at the wrong moment. The lockfile is the record of what was actually installed, and the reason two people running the same command can end up with different code is usually right there in it.

What it actually holds

A lockfile lists every package in the tree, at the exact version that was installed, with the address it came from and a checksum of what arrived. Not the version you asked for - the version that was resolved.

{
  "node_modules/fraunces": {
    "version": "5.3.0",
    "resolved": "https://registry.npmjs.org/fraunces/-/fraunces-5.3.0.tgz",
    "integrity": "sha512-..."
  }
}

The three lines that matter are the version, the address and the checksum. The version says what runs. The address says where it came from. The checksum says the bytes that arrived are the bytes that were published - which is the part that turns a lockfile from a convenience into a safety mechanism.

What it does not hold

A lockfile does not pin your own code, your configuration, or the versions of the tools that run your build. It pins the dependency tree. That distinction is why “it works on my machine” survives a lockfile: the machine is still the machine.

It also does not decide anything about peer dependencies or optional native builds. Those are resolved against the platform at install time, and a lockfile records the resolution it saw, not the one your colleague will see.

Why deleting it is rarely the fix

When a build breaks, the reflex is to remove the lockfile and reinstall, on the theory that the file is the problem. Usually the file is the only record of what went wrong: delete it and you have thrown away the evidence and asked the registry for a fresh roll of the dice. The new install may well be the same, or it may pull a newer transitive dependency you never asked for, and now the failure has moved somewhere else entirely.

The lockfile is only a problem when it is out of step with the manifest - a dependency was added by hand and never installed, or a version was edited in one file and not the other. The fix for that is to run the install and let the tool rewrite the file, not to remove it and hope.

The one rule

Commit the lockfile. It is part of the project, it is what makes an install reproducible, and the checksum it carries is the only thing standing between a published package and a tampered one. A build that cannot be reproduced is a build that cannot be trusted, and the file that would have made it reproducible is the one that was deleted.