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 <script>`	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=dev keeps 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.

Node.js: getting started Files and paths in Node

Last refreshed 2026-09-17.

npm, packages and scripts

package.json

Semantic versioning

Supply-chain hygiene

FAQ

Related