npm & package.json

Why real projects use npm

Small examples fit in one file. Real projects don't. They use code that other people wrote and shared. They also run tools, such as a code checker, before the code goes live. npm and a file called package.json keep track of all of this.

Three words come up all the time:

• A package is shared code plus a few facts about it, such as its name and version.
• A registry is an online store of packages. You can download any version of any package from it.
• A package manager is a program that downloads packages for your project. It also writes down exactly which versions it chose, and it runs your project's commands.

This lesson builds on setting up your tools, why modules exist, import and export, module resolution, and CommonJS and ESM.

The command npm init creates a first package.json for you. Every package manager reads the same main fields from it:

• the project's name and version,
• its commands, called scripts,
• the packages it needs, sorted into groups,
• its sub-projects, called workspaces,
• the files other projects may import from it,
• the Node.js version it expects.

{
  "name": "@acme/color-tools",
  "version": "1.4.2",
  "type": "module",
  "main": "./dist/index.cjs",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    }
  },
  "scripts": {
    "build": "tsc -p tsconfig.build.json",
    "test": "node --test"
  },
  "dependencies": {
    "color-name": "^1.1.4"
  },
  "devDependencies": {
    "typescript": "^5.9.2"
  },
  "peerDependencies": {
    "react": ">=18"
  },
  "optionalDependencies": {
    "fsevents": "^2.3.3"
  },
  "engines": {
    "node": ">=20"
  },
  "private": false,
  "workspaces": ["packages/*"]
}

This is a package.json file, not code to run in the browser. Here is what the first lines mean:

• name and version say which package this is.
• "type": "module" tells Node.js to treat the package's .js files as ES modules, the kind that use import and export.
• exports lists the files that other projects are allowed to import. When it is there, newer Node.js versions use it instead of main, the older single entry file.

{
  "name": "@acme/colors",
  "type": "module",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    },
    "./palette": "./dist/palette.js"
  }
}

This is another package.json, not code to run. The exports field allows two paths:

• The . key is the package itself, @acme/colors. Code that uses import gets index.js. Code that uses require gets index.cjs.
• The ./palette key allows @acme/colors/palette.

Any other path, such as @acme/colors/internal, is not listed, so Node.js refuses to import it. The package must also really contain these files, or the import fails.

The table below lists each field. Read a row as: the field, what it means, and where you can see it in this lesson.

An app and a library use different fields most. An app cares most about scripts, its packages, its tools, private, and workspaces. A library is a package that other projects install. It must get type, main, exports, peerDependencies, and engines right, because other projects import it.

{
  "name": "cf-platform-ui",
  "version": "0.1.0",
  "private": true,
  "workspaces": [
    "packages/*",
    "apps/*"
  ],
  "scripts": {
    "dev": "npm run dev -w cf-client-ui",
    "dev:admin": "npm run dev -w cf-admin-ui",
    "build": "npm run build -w cf-client-ui",
    "build:admin": "npm run build -w cf-admin-ui",
    "start": "npm run start -w cf-client-ui",
    "test:articles": "npm run test:articles -w cf-client-ui",
    "audit:examples": "npm run audit:examples -w cf-client-ui",
    "export:tuto": "npm run export:tuto -w cf-client-ui",
    "lint": "npm run lint -w cf-client-ui",
    "clean": "rm -rf node_modules apps/*/node_modules apps/*/.next apps/*/out && npm cache clean --force"
  }
}

This is the real file from the folder that holds this website's code. That folder holds several apps, so the top file mainly passes work on to them:

• "private": true stops anyone from publishing it to the registry by mistake.
• workspaces says the sub-projects live in packages/* and apps/*.
• Each script uses -w to run a command inside one app, such as cf-client-ui.

{
  "name": "cf-client-ui",
  "version": "0.1.0",
  "private": true,
  "description": "completefrontend.com: the learning site, lessons, and Tuto.",
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "test:articles": "node --experimental-strip-types --test tests/*.test.mjs",
    "export:tuto": "node --experimental-strip-types scripts/export-tuto-notes.mjs",
    "lint": "next lint",
    "audit:examples": "node scripts/audit-examples.mjs"
  },
  "dependencies": {
    "@codemirror/autocomplete": "^6.20.3",
    "@codemirror/commands": "^6.11.1",
    "@codemirror/lang-css": "^6.3.1",
    "@codemirror/lang-html": "^6.4.12",
    "@codemirror/lang-javascript": "^6.2.5",
    "@codemirror/lang-json": "^6.0.2",
    "@codemirror/language": "^6.12.4",
    "@codemirror/lint": "^6.9.7",
    "@codemirror/search": "^6.7.2",
    "@codemirror/state": "^6.7.6",
    "@codemirror/view": "^6.43.13",
    "@completefrontend/design-system": "0.1.0",
    "@lezer/highlight": "^1.2.4",
    "@mdx-js/react": "^3.1.0",
    "@next/mdx": "^15.4.6",
    "acorn": "^8.18.0",
    "acorn-walk": "^8.3.5",
    "codemirror": "^6.0.2",
    "firebase": "^12.19.0",
    "next": "15.4.6",
    "prettier": "^3.9.9",
    "react": "19.1.0",
    "react-dom": "19.1.0",
    "sass": "^1.90.0",
    "sucrase": "^3.35.1"
  },
  "devDependencies": {
    "@eslint/eslintrc": "^3",
    "@mdx-js/loader": "^3.1.0",
    "@mdx-js/mdx": "^3.1.0",
    "@types/node": "^20",
    "@types/react": "^19",
    "@types/react-dom": "^19",
    "eslint": "^9",
    "eslint-config-next": "15.4.6",
    "playwright-core": "^1.63.0",
    "typescript": "^5"
  }
}

This is the real file for the app you are reading right now. Its scripts start, build, and check the site. It splits its packages into two groups:

• dependencies holds packages the site uses while it runs, such as next, react, react-dom, Firebase, the CodeMirror editor, and the site's own design system.
• devDependencies holds tools only the developers use, such as ESLint, TypeScript, the MDX loader, and Playwright.

A package your project needs is called a dependency, because your project depends on it.

When you add or remove a package, npm changes two files: package.json and the lockfile. In package.json, it puts the package in one of two groups. The group says when the package is needed:

• dependencies: packages your app imports and uses while it runs.
• devDependencies: tools you use while building the app, such as a code checker (a linter), a compiler, or a test runner.

npm init -y
npm install react
npm install -D eslint prettier
npm uninstall left-pad
npm run lint
npm run test -- --watch
npm exec -- eslint src/index.js
npx npm-check-updates

Type these in a terminal, in your project's top folder. They don't run in the browser. Line by line:

1. npm init -y creates a package.json. The -y skips the questions and uses the default answers.
2. npm install react adds React to dependencies.
3. npm install -D eslint prettier adds two tools to devDependencies. -D means "dev".
4. npm uninstall left-pad removes a package.
5. npm run lint runs the script named lint.
6. npm run test -- --watch runs the test script and passes it the extra flag --watch.
7. npm exec -- eslint src/index.js runs the ESLint program directly.
8. npx npm-check-updates runs a program too. npx is a short way to write npm exec.

The last four lines run tools. They don't change your package groups. If the program you ask npx for is not installed, npm may offer to download it. Check the name carefully before you say yes.

npm install react
npm install --save-dev eslint
npm ls react
npm uninstall react

Again, these are terminal commands:

1. Line 1 adds React to dependencies.
2. Line 2 adds ESLint to devDependencies. --save-dev is the long form of -D.
3. Line 3, npm ls react, shows where React sits among the installed packages.
4. Line 4 removes React from package.json and updates the lockfile. Another package may still need its own copy of React, so a copy can stay on disk.

Only try line 4 in a practice project. A real React app breaks without React.

{
  "private": true,
  "dependencies": { "react": "19.1.0" },
  "devDependencies": { "eslint": "^9.0.0" }
}

This is a package.json, not code to run. The app imports React, so React is in dependencies. ESLint only checks the code, so it is in devDependencies. The people who build the app run it, and so do automatic checks.

The rule is about how the package is used. A build tool may still need dev packages while it builds the app. But if a server really imports a tool while it runs, that tool belongs in dependencies.

npm puts installed packages in a folder called node_modules. When your code says import React from "react", Node.js looks for a react folder in the nearest node_modules. If it isn't there, Node.js tries the node_modules in the parent folder, then the next one up.

To save space, npm often moves shared packages up to the top node_modules. This is called hoisting. Because of it, your code can import a package you never listed, and it still works on your machine. That hidden package is called a phantom dependency. It breaks later, on another computer or with another package manager, where the package isn't there.

Every package version has three numbers, like 1.4.2. This style is called semver, short for "semantic versioning". The numbers are MAJOR.MINOR.PATCH, and each one has a job:

• MAJOR (the first number) goes up when old code may stop working with the package.
• MINOR (the second number) goes up when the package adds features and old code still works.
• PATCH (the third number) goes up for bug fixes only.

In package.json, you usually don't write one exact version. You write a range: a rule for which versions are OK. For example, this site's app lists ^6.20.3 for a CodeMirror package. The ^ sign is part of the rule. It doesn't install anything by itself.

The table below lists the common rules. Read a row as: the rule's name, how you write it, and which versions it allows.

The two rules you will see most are the caret, ^, and the tilde, ~. This table puts them side by side. Read each row as a question, then the answer for each sign.

const releases = ["1.4.2", "1.4.9", "1.5.0", "2.0.0"];
const tildeMatches = releases.filter((version) => version.startsWith("1.4."));
const caretMatches = releases.filter((version) => version.startsWith("1."));
console.log(tildeMatches.join(", "));
console.log(caretMatches.join(", "));

Line 2 keeps the versions that start with 1.4., like ~1.4.2 would. Line 4 prints 1.4.2, 1.4.9. Line 3 keeps the versions that start with 1., like ^1.4.2 would. Line 5 prints 1.4.2, 1.4.9, 1.5.0.

Checking the start of the text only works here because all four versions are 1.4.2 or higher. Real ranges need real number comparisons, so npm uses its semver package for them.

The function below is a small version of npm's semver package. It handles exact versions, ^, ~, *, and x-ranges like 1.4.x. It skips the rarer cases so you can see the main idea: every rule becomes a lowest allowed version and a first version that is too high. Its answers were checked against npm's real semver package when the lesson was written. The lesson tests check only this small function.

1function parseVersion(version) {Run2  const match = version.match(/^(\d+)\.(\d+)\.(\d+)$/);3  return match && match.slice(1).map(Number);4}5function compare(left, right) {6  for (let index = 0; index < 3; index += 1) {7    if (left[index] !== right[index]) return left[index] < right[index] ? -1 : 1;8  }9  return 0;10}11function plan(range) {12  if (range === "*") return { min: [0, 0, 0], max: [Infinity, 0, 0] };13  if (range.startsWith("^")) {14    const min = parseVersion(range.slice(1));15    const max = min[0] > 0 ? [min[0] + 1, 0, 0] : min[1] > 0 ? [0, min[1] + 1, 0] : [0, 0, min[2] + 1];16    return { min, max };17  }18  if (range.startsWith("~")) {19    const min = parseVersion(range.slice(1));20    return { min, max: [min[0], min[1] + 1, 0] };21  }22  if (/^\d+\.x$/.test(range)) {23    const major = Number(range.split(".")[0]);24    return { min: [major, 0, 0], max: [major + 1, 0, 0] };25  }26  if (/^\d+\.\d+\.x$/.test(range)) {27    const parts = range.split(".").map((part) => part === "x" ? 0 : Number(part));28    return { min: parts, max: [parts[0], parts[1] + 1, 0] };29  }30  const exact = parseVersion(range);31  return exact && { exact };32}33function satisfies(version, range) {34  const versionParts = parseVersion(version);35  const planned = plan(range);36  if (!versionParts || !planned) return false;37  if (planned.exact) return compare(versionParts, planned.exact) === 0;38  return compare(versionParts, planned.min) >= 0 && compare(versionParts, planned.max) < 0;39}40console.log(satisfies("0.2.9", "^0.2.3"));41console.log(satisfies("0.3.0", "^0.2.3"));

1function parseVersion(version) {2  const match = version.match(/^(\d+)\.(\d+)\.(\d+)$/);3  return match && match.slice(1).map(Number);4}5function compare(left, right) {6  for (let index = 0; index < 3; index += 1) {7    if (left[index] !== right[index]) return left[index] < right[index] ? -1 : 1;8  }9  return 0;10}11function plan(range) {12  if (range === "*") return { min: [0, 0, 0], max: [Infinity, 0, 0] };13  if (range.startsWith("^")) {14    const min = parseVersion(range.slice(1));15    const max = min[0] > 0 ? [min[0] + 1, 0, 0] : min[1] > 0 ? [0, min[1] + 1, 0] : [0, 0, min[2] + 1];16    return { min, max };17  }18  if (range.startsWith("~")) {19    const min = parseVersion(range.slice(1));20    return { min, max: [min[0], min[1] + 1, 0] };21  }22  if (/^\d+\.x$/.test(range)) {23    const major = Number(range.split(".")[0]);24    return { min: [major, 0, 0], max: [major + 1, 0, 0] };25  }26  if (/^\d+\.\d+\.x$/.test(range)) {27    const parts = range.split(".").map((part) => part === "x" ? 0 : Number(part));28    return { min: parts, max: [parts[0], parts[1] + 1, 0] };29  }30  const exact = parseVersion(range);31  return exact && { exact };32}33function satisfies(version, range) {34  const versionParts = parseVersion(version);35  const planned = plan(range);36  if (!versionParts || !planned) return false;37  if (planned.exact) return compare(versionParts, planned.exact) === 0;38  return compare(versionParts, planned.min) >= 0 && compare(versionParts, planned.max) < 0;39}40console.log(satisfies("0.2.5", "^0.2.3"));41console.log(satisfies("0.3.0", "^0.2.3"));

Some versions have a label after a dash, like 2.0.0-beta.1. This is a prerelease: a test version before the real release. It counts as lower than 2.0.0. Normal ranges skip prereleases unless the range itself names one.

The registry also has dist-tags such as latest and next. A dist-tag is a name that points at one version. It is not a range.

A range allows many versions on purpose. That helps when you decide to update. But it causes trouble when a teammate, or an automatic check on a server, gets different versions without anyone asking for them.

The lockfile, package-lock.json, stops that. It records three things for every package:

• the exact version npm picked,
• the packages that package needs in turn,
• a hash: a short fingerprint of the download, so npm can tell if the file was changed.

The step-through below follows one made-up package, tiny-color, with the range ^1.4.0. The registry gets new versions over time. Watch which version each install picks.

1function compare(left, right) {2  const a = left.split(".").map(Number);3  const b = right.split(".").map(Number);4  for (let index = 0; index < 3; index += 1) {5    if (a[index] !== b[index]) return a[index] - b[index];6  }7  return 0;8}9function satisfies(version, range) {10  const min = range.slice(1).split(".").map(Number);11  const max = [min[0] + 1, 0, 0];12  return compare(version, min.join(".")) >= 0 && compare(version, max.join(".")) < 0;13}14function resolveLatest(registry, range, date) {15  const row = registry.filter((entry) => entry[0] <= date).at(-1);16  return row[1].filter((version) => satisfies(version, range)).sort(compare).at(-1);17}18const registry = [Run19  ["2026-01-10", ["1.4.0"]],20  ["2026-02-20", ["1.4.0", "1.4.1"]],21  ["2026-05-01", ["1.4.0", "1.4.1", "1.5.0"]],22  ["2026-08-12", ["1.4.0", "1.4.1", "1.5.0", "1.6.2"]],23];24const range = "^1.4.0";25const firstInstall = resolveLatest(registry, range, "2026-02-20");26const freshInstallLater = resolveLatest(registry, range, "2026-08-12");27const packageLock = { dependencies: { "tiny-color": { version: firstInstall } } };28console.log(firstInstall);29console.log(freshInstallLater);30console.log(packageLock.dependencies["tiny-color"].version);

Now pick a date and compare a fresh install with npm ci.

1function compare(left, right) {2  const a = left.split(".").map(Number);3  const b = right.split(".").map(Number);4  for (let index = 0; index < 3; index += 1) {5    if (a[index] !== b[index]) return a[index] - b[index];6  }7  return 0;8}9function satisfies(version, range) {10  const min = range.slice(1).split(".").map(Number);11  const max = [min[0] + 1, 0, 0];12  return compare(version, min.join(".")) >= 0 && compare(version, max.join(".")) < 0;13}14function resolveLatest(registry, range, date) {15  const row = registry.filter((entry) => entry[0] <= date).at(-1);16  return row[1].filter((version) => satisfies(version, range)).sort(compare).at(-1);17}18const registry = [19  ["2026-01-10", ["1.4.0"]],20  ["2026-02-20", ["1.4.0", "1.4.1"]],21  ["2026-05-01", ["1.4.0", "1.4.1", "1.5.0"]],22  ["2026-08-12", ["1.4.0", "1.4.1", "1.5.0", "1.6.2"]],23];24const range = "^1.4.0";25const firstInstall = resolveLatest(registry, range, "2026-02-20");26const freshInstallLater = resolveLatest(registry, range, "2026-08-12");27const packageLock = { dependencies: { "tiny-color": { version: firstInstall } } };28console.log(firstInstall);29console.log(freshInstallLater);30console.log(packageLock.dependencies["tiny-color"].version);

const manifest = { color: "^1.4.0" };
const locked = { color: "1.3.2" };
console.log(locked.color.startsWith("1.4."));
locked.color = "1.4.1";
console.log(locked.color.startsWith("1.4."));

Line 1 is the range from package.json, ^1.4.0. Line 2 is the locked version, 1.3.2. Line 3 prints false, because 1.3.2 is lower than the range allows. Line 4 changes the locked version to 1.4.1, so line 5 prints true.

The startsWith check only works for these two versions. npm uses real version rules and checks every package. If a locked version doesn't fit, npm ci stops with an error. To fix it, run npm install. Don't edit the lockfile by hand.

There are two install commands, and each has its own place:

• Use npm install while you work. It can update the lockfile when you change package.json.
• Use npm ci on a CI server, short for "continuous integration": a computer that tests every change. npm ci needs package.json and the lockfile to match. It deletes node_modules and installs exactly what the lockfile says.

Always save the lockfile in your code history for apps. A library can save one too, for its own tests. Projects that install the library still pick its packages from the library's package.json.

npm install
npm ci
npm ci --omit=dev

Run each of these on its own, in a terminal:

1. npm install uses the versions in the lockfile when they still fit. It picks new versions only when the lockfile is missing or package.json changed.
2. npm ci installs from the lockfile and never changes it.
3. npm ci --omit=dev does the same but leaves out the dev packages. They are still listed in the lockfile. Build and test the app before you use this, because the tools won't be there.

A script is a short name for a long command, saved in the scripts field of package.json. Everyone on the team then runs the same command the same way.

While a script runs, npm lets it use the programs from your installed packages. So next, eslint, tsc, and test tools work without being installed on the whole computer. (Technically, npm adds the folder node_modules/.bin to PATH, the list of folders your terminal searches for programs.)

{
  "scripts": {
    "pretest": "npm run lint",
    "test": "node --test",
    "posttest": "npm run audit:deps",
    "audit:deps": "npm audit --audit-level=high"
  }
}

A script whose name starts with pre runs just before the script with the rest of the name. A script that starts with post runs just after it. These are called hooks. So npm test here runs pretest, then test, then posttest.

To pass an extra flag to a script, put it after two dashes: npm run test -- --watch. The -- tells npm "the rest is not for me, pass it on". To run a package's program directly, use npm exec -- eslint src/index.js, or the shorter npx.

npm run lint
npm exec -- eslint src/index.js
npx eslint src/index.js

These terminal commands use the ESLint installed in your project:

1. npm run lint only works if package.json has a script called lint.
2. npm exec -- eslint src/index.js runs the ESLint program directly.
3. npx eslint src/index.js does the same thing with a shorter command.

If ESLint is not installed, lines 2 and 3 may ask to download it first. On an automatic server, nobody is there to answer. So add the tool to devDependencies first, and let the lockfile record its version.

Hooks also stop on failure. If pretest fails, test doesn't run. And posttest runs only if test passes.

npm is not the only package manager. pnpm, Yarn, and Bun do the same main jobs:

1. read package.json,
2. pick a version for each range,
3. download the packages,
4. put them on disk where Node.js can find them,
5. write a lockfile.

They differ in speed, in how strict they are about phantom dependencies, and in how much disk space they use. The table compares them. Read a row as: the tool, how it puts packages on disk, and when teams pick it.

npm ci
pnpm install --frozen-lockfile
yarn install --immutable

These are three choices, one per package manager. Don't run all three in one project. Each one installs from its own lockfile and stops if the lockfile would need to change:

1. npm ci is for npm.
2. pnpm install --frozen-lockfile is for pnpm.
3. yarn install --immutable is for Yarn 2 and newer, not for Yarn 1.

A project uses one package manager and its lockfile. If you install with a second manager, the two lockfiles will drift apart.

A few details from the current documentation of each tool:

• pnpm keeps one shared copy of each package on your computer. It links each project to those copies. Its node_modules only shows the packages you listed, so most phantom dependencies fail right away.
• Yarn 1 is called Yarn Classic, and Yarn 2 and newer is called Yarn Berry. Berry can skip node_modules completely. Instead it writes a file, .pnp.cjs, that tells Node.js where each package is. This is called Plug'n'Play.
• Bun installs npm packages quickly and writes a text lockfile called bun.lock.

Installing a package means trusting a stranger's code. That code may run in your build, on your server, in your users' browsers, or even while it installs. So check a package before you run npm install:

• Is the name spelled exactly right?
• Who maintains it, and where is its source code?
• How often does it get new releases, and how big is it?
• Does it run scripts when it installs?
• Do you really need it?

npm view react name version repository
npm audit --audit-level=high
npm explain react

These run in a terminal:

1. npm view react name version repository shows the package's exact name, newest version, and source code address. Attackers publish packages with names that look almost the same as popular ones. This trick is called typosquatting.
2. npm audit --audit-level=high lists known security problems in your installed packages. It shows every problem, but it only fails when a problem is rated high or worse.
3. npm explain react shows why React is installed: which package asked for it.

npm audit only knows about problems someone has already reported. A brand-new attack won't show up yet.

npm audit --audit-level=high
npm install --ignore-scripts
npm view react dist-tags versions
npm publish --provenance

These run in a terminal too:

1. npm audit --audit-level=high checks for known problems, as above.
2. npm install --ignore-scripts still installs packages, but it doesn't run their install scripts. Packages that need a build step during install may not work.
3. npm view react dist-tags versions lists React's dist-tags and every published version.
4. npm publish --provenance is for people who publish a package. It attaches a record of where and how the package was built. You don't use it to install.

Be careful with npm audit fix --force. It can jump to a new major version, which may break your app.

{
  "scripts": {
    "preinstall": "node check.js",
    "postinstall": "node build.js"
  }
}

This is a made-up package.json, not code to run. If you install this package, npm may run check.js and build.js on your computer. So before you trust a new package, look at its files and its install scripts, not only its README.

Provenance is a signed record of where a release was built. It helps you check that a release really came from the package's own source code. You should still review a package and its changes before you update your lockfile.

Common misconceptions

• "It works on my computer, so the package must be listed." Not always. Because of hoisting, you can import a package you never listed. Check package.json.
• "The range in package.json is the version I have." No. The range is a rule. The lockfile records the exact version npm picked.
• "CI never installs devDependencies." Most CI jobs install them, because they need the tools to build and test. Only the settings for the live server decide what gets left out.
• "npx installs a program on my whole computer." No. Today npx works like npm exec. It uses the program from your project, or downloads a missing one into npm's cache folder. Check the exact name before you say yes. On automatic servers, add the tool to your packages first.
• "npm audit fixes everything." It helps, but you still need to choose packages carefully, read install scripts, review lockfile changes, and check provenance.

The table compares three things that are easy to mix up. Read a row as a question, then the answer for each file or folder.

Key takeaways

• package.json holds the project's name, its scripts, the files others may import, and the packages it needs.
• Put packages the app imports in dependencies, and tools in devDependencies.
• A range is a rule for which versions are OK. The lockfile records the exact versions npm picked.
• Use npm install while you work, and npm ci on CI servers.
• pnpm, Yarn, and Bun install packages in different ways. You still read package.json and check packages the same way.

Up next: bundlers. A bundler turns your files and installed packages into files a browser can load.