npm & package.json

Why professional tooling starts here

Professional JavaScript begins when your code stops living in one file. You import other modules, run tools before shipping, and trust code written by people you have never met. npm and package.json are the contract for that work.

A package is reusable code plus metadata. A registry stores package names, versions, metadata, and tarballs. A package manager reads your manifest, downloads packages, records exact resolutions, and runs repeatable commands.

This lesson ties back to setting up your tools, why modules exist, import and export, module resolution, and CommonJS and ESM interop.

npm init creates a starter manifest. From there, every package manager reads the same basic fields: identity, scripts, dependency buckets, workspace layout, package entry points, and runtime expectations.

{
  "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/*"]
}

Apps and libraries emphasize different fields. Apps often care most about scripts, dependencies, dev tools, privacy, and workspaces. Published libraries must be more careful with type, main, exports, peers, and engines because other projects import them.

{
  "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"
  }
}

The root package is a monorepo coordinator. It is private, declares packages/* and apps/* as workspaces, and forwards commands to the client or admin app with -w.

{
  "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"
  }
}

The client app manifest is where the learning site’s Next.js scripts live. It lists runtime packages such as next, react, react-dom, Firebase, CodeMirror, and the local design system under dependencies. It lists tools such as ESLint, TypeScript, MDX loaders, and Playwright under devDependencies.

npm changes both the manifest and the lockfile when you add or remove packages. The bucket matters because it documents when a package is needed. A runtime import belongs in dependencies; a linter, compiler, test runner, or generator usually belongs in devDependencies.

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

After installation, Node resolves a bare import such as import React from "react" by looking for a matching package under the nearest node_modules, then walking up parent folders. npm can hoist shared packages higher in the tree to reduce duplication. Hoisting is convenient, but it can hide undeclared “phantom” dependencies until another package manager, CI machine, or production build exposes the missing declaration.

Semver means MAJOR.MINOR.PATCH. The social contract is: breaking changes bump major, new compatible features bump minor, and compatible fixes bump patch. A range such as ^6.20.3 in the real app package does not install a symbol; it describes a set of acceptable versions.

The function below is deliberately smaller than npm’s full semver package. It implements exact versions, ^, ~, *, and x-ranges so you can see the core interval idea without pretending to re-create every edge case. During authoring, its hardcoded expectations were checked against npm’s real semver package; the lesson tests use only this local implementation.

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"));

Prerelease tags add one more rule: 2.0.0-beta.1 sorts before 2.0.0, and ordinary stable ranges do not automatically include prereleases. Registry dist-tags such as latest and next are labels pointing to versions, not semver ranges.

A package range is intentionally flexible. That flexibility is useful when you choose to update; it is dangerous when a teammate or CI job gets a different dependency graph without meaning to. package-lock.json records the exact versions, nested dependencies, and integrity hashes npm resolved.

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}Run18const 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);

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);

Use npm install while developing because it can update the lockfile when your manifest changes. Use npm ci in CI because it requires the manifest and lockfile to agree, removes node_modules, and installs exactly what the lockfile says. Commit lockfiles for applications and repositories; published libraries can still commit one for their own tests even though consumers resolve their dependencies from the manifest.

npm scripts turn long commands into shared names. When a script runs, npm adds local package binaries to PATH, so next, eslint, tsc, and test tools can run without global installs.

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

Running npm test here would run pretest, then test, then posttest. To pass flags to the underlying script, put them after a double dash: npm run test -- --watch. To run a package binary directly, use npm exec eslint -- src/index.js or the familiar npx command.

Package managers share the same broad job: read the manifest, resolve versions, fetch packages, lay them out for the runtime, and write a lockfile. Their differences show up in speed, strictness, disk usage, compatibility, and team workflow.

Current pnpm documentation describes a content-addressable store and a symlinked node_modules structure that avoids many phantom dependencies. Current Yarn docs distinguish Yarn Classic from Yarn Berry and explain Plug'n'Play through a .pnp.cjs loader instead of a traditional node_modules tree. Bun’s package manager can install npm packages quickly and now uses a text bun.lock by default.

Installing a package is a trust decision. You are downloading code that may run in your build, your server, your users’ browsers, or even during installation. Security starts before npm install: check the name, maintainer, repository, release history, package size, install scripts, and whether the dependency is truly needed.

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

npm audit reports known vulnerabilities in the resolved dependency graph. It is a signal, not a complete review. Typosquatting attacks rely on names that look almost right. npm provenance lets publishers attach build provenance to releases, making it easier to verify where a package came from.

Common misconceptions

• “If it works locally, the dependency must be declared correctly.” Hoisting can hide phantom dependencies. Check the manifest.
• “The range in package.json is the installed version.” The range is intent; the lockfile records the concrete resolution.
• “devDependencies are never installed in CI.” Most CI jobs install dev tools to build and test. Production deployment settings decide what is pruned.
• “npx means global install.” Modern npm uses exec behavior: prefer local bins and ask before fetching missing packages.
• “npm audit fixes everything.” Audit data helps, but package choice, lifecycle scripts, lockfile review, and provenance still matter.

Key takeaways

• package.json declares identity, scripts, package entry points, and dependency intent.
• Use dependencies for runtime or bundled code and devDependencies for tools.
• Semver ranges describe allowed versions; lockfiles record exact resolved versions.
• npm ci is the repeatable CI install path; npm install is for development changes.
• pnpm, Yarn Berry, and Bun change install strategy, but the manifest and supply-chain habits still matter.

Up next: Bundlers turn installed modules and your source files into browser-ready assets.