npm, packages and scripts
package.json, semantic versioning, lockfiles, and the scripts and workspaces that keep a project reproducible.
package.json
{
"name": "my-api",
"version": "1.4.0",
"type": "module",
"scripts": {
"start": "node src/server.js",
"dev": "node --watch src/server.js",
"test": "node --test"
},
"engines": { "node": ">=20" },
"dependencies": { "express": "^4.19.0" },
"devDependencies": { "eslint": "^9.0.0" }
}| Command | Effect |
|---|---|
npm install | Install exactly what the lockfile pins |
npm ci | Clean install for CI — faster and reproducible |
npm outdated | Show available updates |
npm audit | Report known vulnerabilities |
npm run | Run a script from package.json |
⚠️
Always commit
package-lock.json and use npm ci in CI. Without a lockfile two machines can resolve different versions of the same dependency tree.Semantic versioning
| Range | Meaning |
|---|---|
1.4.2 | Exactly this version |
^1.4.2 | Any 1.x ≥ 1.4.2 — accepts new features |
~1.4.2 | Any 1.4.x — patch updates only |
1.4.x / * | Loose; avoid in applications |
MAJOR.MINOR.PATCH: a major bump may break your code, a minor one adds functionality compatibly, and a patch fixes bugs. Ranges assume maintainers follow that contract — hence the lockfile.
Supply-chain hygiene
- Fewer dependencies means less attack surface; check whether a 2 kB need justifies a package.
- Pin or lock transitive dependencies, and run
npm audit(or Dependabot) regularly. - Typosquatting is real: verify the exact package name and its download count before installing.
npm ci --omit=devkeeps dev-only tooling out of production images.
💡
Post-install scripts run arbitrary code at install time. In sensitive environments use
--ignore-scripts and build explicitly.FAQ
dependencies or devDependencies?
Runtime needs go in
dependencies; test runners, linters and bundlers go in devDependencies so production installs stay lean.Should I use npx?
Yes for one-off CLIs (
npx eslint .). Prefer a local devDependency plus an npm script for anything the team runs repeatedly.Related
Node.js: getting started Files and paths in Node
Last refreshed 2026-09-17.