Dependencies and version ranges
A dependency is a package that another package needs, written in package.json with a version that is a range and not a number. npm resolves the range against the registry, writes the answer into the lock file and puts the code into node_modules; the range stays in the manifest, because it says what the package can work with and not what it happened to get.
The lesson installs two packages into one folder: ms 2.1.2, which the program needs while it runs, and semver 7.8.5, which a developer needs while the code is written. It then reads the ranges with semver, lists the installed tree with npm ls and asks the registry what is newer with npm outdated.
dependencies against devDependencies
dependencies holds what the code imports when it runs: npm install --omit=dev installs those and nothing else, which is what a server image needs. devDependencies holds what a developer needs and a deployment does not: a linter, a formatter, a test runner. A package that is only imported by a test file belongs in the second table, and npm writes to the first one unless asked otherwise.
The two install commands differ by one flag. npm prints how many packages it added and how long it took; the file it writes is the part worth reading, and the version after the name is the exact one that was installed, not the range that was saved.
npm init -y
npm install ms@2.1.2
npm install --save-dev semver@7.8.5
The file package.json:
{
"name": "deps-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"
}
}
Both entries carry the caret that npm writes by default, and both name a version that exists and was installed. The program prints the two tables and the range of each entry.
The file kinds.js:
const { readFileSync } = require('node:fs');
const pkg = JSON.parse(readFileSync('package.json', 'utf8'));
for (const [kind, table] of [['dependencies', pkg.dependencies], ['devDependencies', pkg.devDependencies]]) {
console.log(kind + ':');
for (const [name, range] of Object.entries(table ?? {})) {
console.log(' ' + name + ' at ' + range);
}
}
node kinds.js
dependencies:
ms at ^2.1.2
devDependencies:
semver at ^7.8.5
The program that ships uses ms and nothing else, which is the test of the first table: a name that the runtime code needs belongs there. The second package is a tool, and the same program that reads the ranges can find out whether an entry is needed at run time.
The file duration.js:
const ms = require('ms');
console.log('two hours in milliseconds:', ms('2h'));
console.log('the runtime needs only this one package');
node duration.js
two hours in milliseconds: 7200000
the runtime needs only this one package
One require by name and the resolver finds the package in node_modules, which is the whole point of the two tables: the folder is rebuilt from the manifest, and never committed.
Caret and tilde
A version has three numbers, and semantic versioning gives each of them a meaning: the first is a breaking change, the second adds something without breaking, the third fixes a bug. A range is a rule over those numbers. ^1.2.3 allows any 1.x.y at or above 1.2.3, ~1.2.3 allows only 1.2.y, and a bare 1.2.3 allows exactly that version.
semver is the package npm itself uses to read the rules. The program asks it what three ranges mean and whether four versions satisfy them, which turns the table of the manual into output.
The file ranges.js:
const semver = require('semver');
const ranges = ['1.2.3', '^1.2.3', '~1.2.3'];
for (const range of ranges) {
console.log(range, 'means', semver.validRange(range));
}
console.log('2.0.0 satisfies ^1.2.3:', semver.satisfies('2.0.0', '^1.2.3'));
console.log('1.9.0 satisfies ^1.2.3:', semver.satisfies('1.9.0', '^1.2.3'));
console.log('1.9.0 satisfies ~1.2.3:', semver.satisfies('1.9.0', '~1.2.3'));
console.log('1.2.9 satisfies ~1.2.3:', semver.satisfies('1.2.9', '~1.2.3'));
node ranges.js
1.2.3 means 1.2.3
^1.2.3 means >=1.2.3 <2.0.0-0
~1.2.3 means >=1.2.3 <1.3.0-0
2.0.0 satisfies ^1.2.3: false
1.9.0 satisfies ^1.2.3: true
1.9.0 satisfies ~1.2.3: false
1.2.9 satisfies ~1.2.3: true
The expanded forms are the clearest part: the caret is a pair of bounds that stops before the next major version, and the tilde stops before the next minor one. The -0 at the end of each upper bound is how semver excludes a prerelease of the version that would be the next one; the next lesson writes the resolved versions down so that two machines agree.
npm ls
npm ls walks node_modules and prints what is installed, which is not always what the manifest asks for. --depth 0 stops at the direct dependencies, and --json gives the same tree as an object that a program can read.
The program keeps the name and the version of each entry and prints them with two spaces of indentation, which is the whole shape of the command.
The file tree.js:
let text = '';
process.stdin.setEncoding('utf8');
process.stdin.on('data', (chunk) => {
text += chunk;
});
process.stdin.on('end', () => {
const tree = JSON.parse(text);
console.log(tree.name + '@' + tree.version);
for (const [name, info] of Object.entries(tree.dependencies ?? {})) {
console.log(' ' + name + '@' + info.version);
}
});
npm ls --depth 0 --json | node tree.js
deps-course@1.0.0
ms@2.1.2
semver@7.8.5
Two direct dependencies and no transitive ones, because both packages have none of their own. In a real project the JSON has a dependencies object per entry, and the depth flag decides how many levels of it are printed. A package that is in the folder but not in the manifest is marked extraneous, and npm ls exits with 1 for it.
npm outdated
current is the version in node_modules, wanted is the newest version that still satisfies the range in the manifest, and latest is the newest version of the package at all. A row where wanted and latest differ is a major upgrade, which the caret deliberately does not take.
Both entries were installed at the exact version asked for, which is older than the range allows, so both have a row. The program prints the three numbers and drops the rest of the JSON, which also carries the folder of each package.
The file outdated.js:
let text = '';
process.stdin.setEncoding('utf8');
process.stdin.on('data', (chunk) => {
text += chunk;
});
process.stdin.on('end', () => {
const report = JSON.parse(text);
for (const [name, info] of Object.entries(report)) {
console.log(name + ': current ' + info.current + ', wanted ' + info.wanted + ', latest ' + info.latest);
}
});
npm outdated --json > /dev/null
echo "npm outdated exits with: $?"
npm outdated --json | node outdated.js
npm outdated exits with: 1
ms: current 2.1.2, wanted 2.1.3, latest 2.1.3
semver: current 7.8.5, wanted 7.8.6, latest 7.8.6
The command exits with 1 when it has something to report, which makes it a check and not only a table: npm outdated > /dev/null && echo up to date answers the question in a script. The versions above are the registry's answer on the day the page was written, and the lock file lesson shows what a reader gets instead of this answer.
Exercises
- Install a package with --save-dev and one without it, then print both tables. Which flag decides the table, and which one does npm print in its summary?
- Compare ^1.2.3 and ~1.2.3 with semver.validRange. Which part of the version does each bound freeze?
- Ask semver.satisfies about 1.2.3-beta.1 and ^1.2.3. What does a prerelease need before a range accepts it?
- Run npm ls --depth 0 after installing one more package. Which entry appears twice in the plain tree, and why does the JSON not repeat it?
- Change a range to a version that does not exist and run npm install. Which command reports the problem first, and does the folder change?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
Which table holds a package that only a test file imports?
Answer
devDependencies
A deployment installs dependencies alone, so a tool that only a developer needs goes in the second table.
-
What does
^1.4.2allow?Answer
Any 1.x.y at or above 1.4.2
The caret moves the minor and the patch but stops before the next major version.
-
What does this program print?
const semver = require("semver"); console.log(semver.validRange("~1.2.3"));Answer
>=1.2.3 <1.3.0-0
The tilde allows patch releases of 1.2 and nothing above them.
-
What does the caret do when npm writes
"ms": "^2.1.2"afternpm install ms@2.1.2?Answer
It saves the installed version as the lower bound of a range
npm installs the version on the command line and saves the default range around it.
-
What does
npm ls --depth 0print?Answer
The direct dependencies and their installed versions
The depth flag stops the walk at the first level of the installed tree.
-
What does this program print?
const semver = require("semver"); console.log(semver.satisfies("1.9.0", "^1.2.3"), semver.satisfies("1.9.0", "~1.2.3"));Answer
true false
The minor version may rise under a caret but not under a tilde.
-
What is the
wantedversion in the report ofnpm outdated?Answer
The newest version the range in the manifest allows
It is the answer to the range and the target of a plain update; latest can be higher than it.
-
What does this program print?
const pkg = { dependencies: { ms: "^2.1.2" }, devDependencies: { semver: "^7.8.5" } }; console.log(Object.keys(pkg.dependencies).join(","), Object.keys(pkg.devDependencies).length);Answer
ms 1
The first table has one key, and the second answers its count, which is also one.
-
What does
npm outdatedanswer when every installed version is the newest allowed one?Answer
Nothing, and the exit status is 0
A report with no rows prints nothing, and only a row makes the command exit with 1.
-
What does this program print?
const ranges = ["1.2.3", "^1.2.3", "~1.2.3"]; console.log(ranges.filter((range) => range.startsWith("^")).length);Answer
1
Only the second entry starts with a caret; the bare version and the tilde do not.
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 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