npm, semver and lock files

Almost every JavaScript project is built from other people’s code. npm downloads it (it ships with Node) from the npm registry. The beginner lesson on package.json added one dependency. This lesson does it deliberately: what version numbers promise, what the lock file protects you from, and how a package decides what others may import.

Listings that need the network (npm install, npx) are pasted from real runs on 17 October 2026 with npm 11.20.0 on Node 26.11.1, so your numbers will differ. Listings that need only Node are checked on Node 22, 24 and 26.

Semantic versions

Package versions follow semantic versioning (semver): three numbers, MAJOR.MINOR.PATCH, for example 2.4.1.

• PATCH goes up for bug fixes that change no behaviour you could depend on.
• MINOR goes up when features are added in a compatible way.
• MAJOR goes up when something may break existing users.

It is a promise by the author, only as good as their discipline. The parts are compared as numbers: 1.10.0 is newer than 1.9.0, although as text "1.10.0" sorts first. A hyphen, as in 2.0.0-beta.1, marks a prerelease: it comes before 2.0.0 and ordinary ranges do not match it.

Ranges in package.json

The dependencies of a package.json do not name one version. They name a range of acceptable versions:

The caret ^ is what npm install some-package writes by default. Below 1.0.0 the rule is stricter, because anything may change in 0.x software: ^0.2.3 means >=0.2.3 <0.3.0, and ^0.0.3 means exactly 0.0.3.

npm decides with the semver package, which has a command-line tool that prints the versions that fit a range. Run it with npx, which downloads a package’s command on first use.

$ npx semver -r '^1.2.3' 0.0.3 1.2.3 1.3.0 1.9.0 2.0.0
1.2.3
1.3.0
1.9.0
$ npx semver -r '~1.2.3' 0.0.3 1.2.3 1.2.9 1.3.0 2.0.0
1.2.3
1.2.9
$ npx semver -r '^0.2.3' 0.0.3 0.2.9 0.3.0 1.2.3
0.2.9
$ npx semver -r '^0.0.3' 0.0.3 0.0.4 0.2.9
0.0.3
$ npx semver -r '^2.0.0' 2.0.0-beta.1 2.0.0 2.1.0
2.0.0
2.1.0
$ npx semver 1.10.0 1.9.0 1.2.3
1.2.3
1.9.0
1.10.0

Without -r the tool sorts, and 1.9.0 comes before 1.10.0. The beta did not match ^2.0.0. (semver 7.8.5.)

Installing, locking and updating

npm install reads the ranges in package.json, picks the newest matching version of every package (and of the packages those need), puts them in node_modules, and writes the choice into package-lock.json. In a fresh folder:

$ npm init -y
$ npm install is-odd@^3.0.0

added 2 packages, and audited 3 packages in 534ms

found 0 vulnerabilities

npm init -y wrote this package.json, and npm install added the last four lines:

{
  "name": "proj",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "type": "commonjs",
  "dependencies": {
    "is-odd": "^3.0.1"
  }
}

The range is the newest version at the time, with a caret. The lock file records what was installed, where it came from and an integrity hash:

    "node_modules/is-odd": {
      "version": "3.0.1",
      "resolved": "https://registry.npmjs.org/is-odd/-/is-odd-3.0.1.tgz",
      "integrity": "sha512-CQpnWPrDwmP1+SMHXZhtLtJv90yiyVfluGsX5iNCVkrhQtU3TQHsUWPG9wkdk9Lgd5yNpAg9jQEo90CBaXgWMA==",
      "license": "MIT",
      "dependencies": {
        "is-number": "^6.0.0"
      },

So package.json states what you will accept, a range, and package-lock.json what you got, an exact tree. Commit both: the lock file makes every install the same, instead of whatever is newest that day.

• npm install follows the ranges and may change the lock file.
• npm ci (clean install) deletes node_modules and installs exactly what the lock file says. If the two files disagree it stops and changes nothing. Use it in CI and in deployments.

That is the safety net. Change the range to ^2.0.0 without updating the lock file and npm ci refuses. This error block is shortened: the real message goes on to print npm’s usage text.

$ 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 is-odd@3.0.1 does not satisfy is-odd@2.0.0
npm error Invalid: lock file's is-number@6.0.0 does not satisfy is-number@4.0.0
npm error
npm error Clean install a project
(shortened: npm then prints its usage text)

Other commands: npm outdated (installed, wanted, latest), npm update (newest versions the ranges allow), npm ls (the tree), npm audit (known vulnerabilities), npm uninstall name. Use npm install --save-dev name (-D) for tools only development needs, such as a linter; they go in devDependencies.

Scripts

The "scripts" field names commands for the project, so every contributor has the same few words: npm test, npm start, npm run build. Here is a complete package.json with two scripts:

{
  "name": "np-scripts",
  "version": "1.0.0",
  "scripts": {
    "hello": "node -p \"'hello from a script'\"",
    "show": "node -p \"process.argv.slice(1).join(' ')\""
  }
}

npm run hello runs one. Node can run them itself with node --run, available from Node 22.0 (from 22.3 it also finds a package.json in a parent folder). It starts faster than npm run, but is deliberately smaller: no pre and post scripts, no npm environment variables, and --env-file variables are not passed to the script. Arguments after -- are appended to the command.

$ node --run hello
hello from a script
$ node --run show -- one two
one two

npx

npx runs a command that a package provides. It looks in your project’s node_modules/.bin first; otherwise it downloads the package into a cache and runs it, as with semver above. Running a name you do not know means running someone else’s code with your permissions, so check it: typos of popular package names are a known trick.

What a package exposes: exports

Without configuration, import "greeter/src/internal.js" reaches every file inside an installed package, and people will, which freezes your file layout forever. The exports field lists the public paths; nothing else can be imported from outside. The imports field names private shortcuts inside your own package; names start with #, and * stands for any text.

A package with exports can import itself by name, the easiest way to try this without installing anything; other packages see the same map. The folder np_demo:

np_demo/
  package.json
  app.mjs
  lib/util.js
  src/main.js   src/extra.js   src/internal.js
  src/dual.mjs  src/dual.cjs

src/main.js exports greet, src/extra.js exports shout, lib/util.js exports twice, src/internal.js exports secret, and the two dual files each export a string, "esm build" and "cjs build". The map makes three of these public:

{
  "name": "np-demo",
  "version": "1.0.0",
  "type": "module",
  "exports": {
    ".": "./src/main.js",
    "./extra": "./src/extra.js",
    "./dual": { "import": "./src/dual.mjs", "require": "./src/dual.cjs" }
  },
  "imports": { "#lib/*": "./lib/*.js" }
}

An entry can depend on how the package is loaded: "./dual" has one file for import and one for require, as a package ships ES module and CommonJS builds (why both exist). The app uses the public names and the private #lib/util, then reaches for a file that is not exported.

import { createRequire } from "node:module";
import { greet } from "np-demo";
import { shout } from "np-demo/extra";
import dual from "np-demo/dual";
import { twice } from "#lib/util";

console.log(greet("Ada"), shout("hi"), twice(21));
console.log(dual, "|", createRequire(import.meta.url)("np-demo/dual"));
await import("np-demo/src/internal.js").catch((e) => console.log(e.code));

$ node app.mjs
Hello, Ada! HI 42
esm build | cjs build
ERR_PACKAGE_PATH_NOT_EXPORTED

The public names came through exports, with different files for import and require; #lib/util came through imports; and np-demo/src/internal.js was refused with ERR_PACKAGE_PATH_NOT_EXPORTED, although the file exists.

Workspaces

A monorepo keeps several packages in one repository, such as a library and its app. With the workspaces field in the root package.json, npm installs all their dependencies at once and links packages from the same repository into node_modules instead of downloading them.

{
  "name": "root",
  "private": true,
  "workspaces": ["packages/*"]
}

If b lists a in its dependencies, one npm install at the root links both to their folders, so import "a" in b sees the current source of a with no publishing step. npm run build --workspaces --if-present runs a script in every workspace that defines it.

Common pitfalls

• Not committing package-lock.json. Every install can then produce a different tree.
• Using npm install in CI. Use npm ci, which fails when the files disagree.
• Editing or committing node_modules. It is generated; add it to .gitignore.
• Putting a test tool in dependencies. Users of your package download it too. Use devDependencies.
• Comparing versions as strings. "1.10.0" > "1.9.0" is false. Use a semver library.
• Expecting ^0.x to float like ^1.x. For 0.x versions the caret allows far less.
• Installing packages without looking. Every dependency is code you did not write. Check what a package pulls in with npm ls.
• Importing package/dist/internal.js from a package without exports. It may vanish in the next release.

Exercises

{
  "name": "bump-demo",
  "version": "1.2.3"
}

$ npm version patch --no-git-tag-version
v1.2.4
$ npm version minor --no-git-tag-version
v1.3.0
$ npm version major --no-git-tag-version
v2.0.0
$ npm pkg get version
"2.0.0"

{
  "name": "mathy",
  "version": "1.0.0",
  "type": "module"
}

export default (a, b) => a + b;
// lib/mul.js
export default (a, b) => a * b;

import add from "mathy/add";
import mul from "mathy/mul";

console.log(add(2, 3), mul(2, 3));
await import("mathy/missing").catch((e) => console.log(e.code));

$ node app.mjs
5 6
ERR_MODULE_NOT_FOUND

{
  "name": "mathy",
  "version": "1.0.0",
  "type": "module",
  "exports": { "./*": "./lib/*.js" }
}

$ npx semver -r '1.x' 0.9.0 1.0.0 1.4.9 1.5.0 2.0.0 3.1.0
1.0.0
1.4.9
1.5.0
$ npx semver -r '>=1.2.3 <1.5.0' 0.9.0 1.0.0 1.4.9 1.5.0 2.0.0 3.1.0
1.4.9
$ npx semver -r '^1.2.3 || ^3.0.0' 0.9.0 1.0.0 1.4.9 1.5.0 2.0.0 3.1.0
1.4.9
1.5.0
3.1.0

Summary

• Versions are MAJOR.MINOR.PATCH and compared number by number. ^1.2.3 allows >=1.2.3 <2.0.0, ~1.2.3 allows >=1.2.3 <1.3.0, and ^0.x is narrower. npx semver -r RANGE VERSIONS... shows what a range accepts.
• package.json holds the ranges you accept. package-lock.json holds the exact tree you got, with integrity hashes. Commit both.
• npm install follows ranges and may update the lock file. npm ci installs exactly what the lock file says and fails if the two disagree: use it in CI.
• npm run and node --run (Node 22.0 and later; no pre/post scripts) run the scripts. npx runs a package’s command.
• exports lists what a package makes public, with conditions such as import and require and patterns with *. imports defines private #names inside your own package.
• workspaces link several packages of one repository together.

That completes the Node essentials. Next module: testing and tooling, starting with Node’s built-in test runner.