Lockfiles and npm ci
npm writes two files with one command. The manifest keeps the ranges that were asked for, and package-lock.json keeps the exact versions that were chosen for every package in the tree, direct and transitive. The manifest is a request and the lock file is the answer, so the same two files produce the same node_modules on every machine.
The lesson reads the lock file field by field, compares it with the ranges of the manifest, installs the same project from the two files in a fresh folder with npm ci, and then breaks the pair on purpose to read the error that a build server would show.
What npm install writes
The two packages of the previous lesson were installed at the exact version on the command line, so the folder starts with an old version of each and a range that would accept a newer one. That gap is what the lock file records.
npm init -y
npm install ms@2.1.2
npm install --save-dev semver@7.8.5
The file package.json:
{
"name": "lock-course",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC",
"type": "commonjs",
"dependencies": {
"ms": "^2.1.2"
},
"devDependencies": {
"semver": "^7.8.5"
}
}
The coloured lines are the ones this lesson reads: the name and version of the project, its module type, and the two tables the installs wrote. The other fields are the defaults that npm init -y puts into every new package.json.
The lock file has one object per installed package, keyed by its path inside node_modules. The empty key is the project itself, and each entry carries the version, the address the tarball came from and the hash of its contents.
The file package-lock.json, the first lines:
{
"name": "lock-course",
"version": "1.0.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "lock-course",
"version": "1.0.0",
"dependencies": {
"ms": "^2.1.2"
},
"devDependencies": {
"semver": "^7.8.5"
}
},
"node_modules/ms": {
"version": "2.1.2",
"resolved": "https://registry.npmjs.org/ms/-/ms-2.1.2.tgz",
"integrity": "sha512-sGkPx+VjMtmA6MX27oA4FBFELFCZZ4S4XqeGOXCv68tT+jb3vk/RyaKWP0PTKyWtmLSM0b+adUTEvbs1PEaH2w==",
"license": "MIT"
},
The program prints the version and the first characters of the hash of each entry, which is the part a reader checks when two machines disagree. The rest of the file is one block per package, and a real project has hundreds of them.
The file lock-summary.js:
const { readFileSync } = require('node:fs');
const lock = JSON.parse(readFileSync('package-lock.json', 'utf8'));
console.log('lockfileVersion:', lock.lockfileVersion);
for (const [key, info] of Object.entries(lock.packages)) {
if (key === '') {
continue;
}
console.log(key + ' is ' + info.version + ', integrity ' + info.integrity.slice(0, 20) + '...');
}
node lock-summary.js
lockfileVersion: 3
node_modules/ms is 2.1.2, integrity sha512-sGkPx+VjMtmA6...
node_modules/semver is 7.8.5, integrity sha512-Y7/KDsb8LjooZ...
The block version 3 belongs to npm 7 and later, and the path key is what places a package inside a nested node_modules: a package that needs another version of the same dependency gets its own entry at node_modules/a/node_modules/b. The hash in integrity is checked on every install, so a tarball that changed on the registry stops the install instead of entering the tree.
Why the file is committed
The manifest says ^2.1.2, which is true of every release of ms from 2.1.2 to before 2.0.0 of the next major line. Two machines that install from the manifest alone can therefore get two different versions, and the version that was tested is not the version that ships. The lock file is the only record of that version, so it goes into git beside the manifest.
The program prints each requirement next to the version the lock file recorded for it.
The file compare.js:
const { readFileSync } = require('node:fs');
const pkg = JSON.parse(readFileSync('package.json', 'utf8'));
const lock = JSON.parse(readFileSync('package-lock.json', 'utf8'));
for (const table of [pkg.dependencies, pkg.devDependencies]) {
for (const [name, range] of Object.entries(table ?? {})) {
const locked = lock.packages['node_modules/' + name].version;
console.log(name + ': required ' + range + ', locked ' + locked);
}
}
node compare.js
ms: required ^2.1.2, locked 2.1.2
semver: required ^7.8.5, locked 7.8.5
Both requirements and both locked versions agree, and both locked versions are the ones that were asked for on the command line, not the newest the range allows. A dependency of a dependency has no line in the manifest at all and only an entry in the lock file, which is the second reason the file is committed: it pins the code that nobody named.
npm ci in a fresh copy
npm ci is the install of a build server. It deletes node_modules, installs exactly the versions in the lock file, and never writes package.json or the lock. A copy of the project with two files and no folder is enough to show it.
mkdir ../clone
cp package.json package-lock.json installed.js lock-summary.js ../clone/
cd ../clone
npm ci --silent
node installed.js
The file installed.js:
const { readFileSync } = require('node:fs');
const pkg = JSON.parse(readFileSync('package.json', 'utf8'));
const names = Object.keys({ ...pkg.dependencies, ...pkg.devDependencies });
for (const name of names) {
const path = 'node_modules/' + name + '/package.json';
try {
console.log(name + '@' + JSON.parse(readFileSync(path, 'utf8')).version);
} catch {
console.log(name + ' is not installed');
}
}
ms@2.1.2
semver@7.8.5
The copy has no manifest of its own that differs and no folder to start from, and the versions are the ones in the lock. npm ci --silent printed nothing at all; without the flag it prints the count of packages and the time, which are not worth a line here. The command is also faster than npm install on a build server, because it skips the work of choosing versions.
Out of sync, and the repair
A lock file is only useful if it matches the manifest. Change the range of ms to ^2.1.3 by hand, as a merge or a colleague would, and the lock still records 2.1.2, which does not satisfy the new requirement. npm ci refuses to guess.
vi package.json
npm ci
npm error code EUSAGE
npm error
npm error `npm ci` can only install packages when your package.json and package-lock.json or npm-shrinkwrap.json are in sync. Please update your lock file with `npm install` before continuing.
npm error
npm error Invalid: lock file's ms@2.1.2 does not satisfy ms@2.1.3
The message names the pair and the version that does not fit, and then prints the usage of the command, which is the part left out here. The repair is the command the message names, and it changes both files: the manifest keeps the range and the lock gets the version that satisfies it.
npm install --silent
node installed.js
node lock-summary.js
ms@2.1.3
semver@7.8.5
lockfileVersion: 3
node_modules/ms is 2.1.3, integrity sha512-6FlzubTLZG3J2...
node_modules/semver is 7.8.5, integrity sha512-Y7/KDsb8LjooZ...
Only ms moved. npm install resolves what the lock does not satisfy and leaves every entry that already fits alone, so semver stayed at 7.8.5 although a newer patch exists. That is the difference between the two commands in one sentence: npm ci installs the lock or stops, and npm install edits the lock until it fits.
Exercises
- Delete package-lock.json and run npm install. Which versions appear in the new lock, and why is that answer a reason to commit the old one?
- Print the resolved field of one entry. Which two facts does the pair of resolved and integrity pin?
- Run npm ci twice in a row. What happens to node_modules between the runs, and how long does the second one take?
- Add a dependency with npm install and run npm ci in a copy that has the old lock. Which line of the error names the package that is missing from the lock?
- Find a package in the lock that is not in the manifest. Which package asked for it, and which field of the lock says so?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What does package-lock.json record?
Answer
The exact version of every package in the tree
The manifest keeps the ranges and the lock keeps the resolved version of each entry, transitive ones included.
-
What does
npm cido when package.json and package-lock.json disagree?Answer
It stops and asks for npm install
The clean install has one job, and a lock that does not match the manifest makes that job impossible.
-
What does this program print?
const lock = { packages: { "": { name: "app" }, "node_modules/ms": { version: "2.1.3" } } }; console.log(Object.keys(lock.packages).length);Answer
2
The empty key is the project itself and the second key is the one package.
-
Why is a lock file committed for an application?
Answer
So that the tested versions are the versions that ship
The file pins what was tested; the ranges alone leave the choice to the machine.
-
What does this program print?
const lock = { packages: { "node_modules/a": { version: "1.0.0" }, "node_modules/b": { version: "2.0.0" } } }; const versions = Object.entries(lock.packages).filter(([key]) => key !== "").map(([, info]) => info.version); console.log(versions.join(" "));Answer
1.0.0 2.0.0
The entries keep the order of the object and the filter only drops the project itself.
-
Which field of a lock entry is checked against the downloaded tarball?
Answer
integrity
The hash of the contents decides whether the bytes are the ones that were recorded.
-
What does this program print?
const pkg = { dependencies: { ms: "^2.1.2" } }; const lock = { packages: { "node_modules/ms": { version: "2.1.2" } } }; console.log(pkg.dependencies.ms === "^" + lock.packages["node_modules/ms"].version);Answer
true
The two strings are the same five characters, which is what agreement means here.
-
What is the difference between npm ci and npm install?
Answer
ci installs the lock and stops, install edits the lock to fit
The clean install treats the pair of files as read-only; the ordinary one repairs the pair.
-
What does this program print?
const lock = { lockfileVersion: 3, packages: {} }; console.log(Object.keys(lock.packages).length === 0, lock.lockfileVersion > 2);Answer
true true
The empty map has no keys, and the version is the third of the format.
-
A dependency of a dependency is not in package.json. Where is its version recorded?
Answer
Only in package-lock.json
The lock file covers the whole tree, which is why it can pin the code that nobody named.
The programs and commands on this page were run with Node.js 24.22.1 and npm 11.12.1 against ms 2.1.2, ms 2.1.3 and semver 7.8.5 from the public registry, and linted with ESLint 10.14.0 on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev