npm, package.json and Dependencies

{
  "name": "toolhub",
  "type": "module",
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "typecheck": "tsc --noEmit"
  },
  "dependencies": {          // shipped to the browser / needed at runtime
    "next": "14.2.5",        // exact
    "zod": "^3.23.0"         // >=3.23.0 <4.0.0
  },
  "devDependencies": {       // build and test only, not shipped
    "typescript": "~5.5.0",  // >=5.5.0 <5.6.0
    "vitest": "^2.0.0"
  },
  "engines": { "node": ">=20" }
}

// Ranges
// ^1.2.3  -> minor and patch updates   (the default npm adds)
// ~1.2.3  -> patch updates only
// 1.2.3   -> exactly this
// Below 1.0.0, ^ behaves like ~ — 0.x is treated as unstable.

// Run scripts
npm run build
npx tsc --noEmit        // run a binary without installing it globally

// package.json says  "zod": "^3.23.0"
// You installed in January -> 3.23.1
// A teammate installs in March -> 3.24.5
// Same manifest, different code, and a bug only one of you can see.

// package-lock.json records the exact resolved tree, including
// transitive dependencies. COMMIT IT.

npm install     // may update the lockfile
npm ci          // installs exactly the lockfile, fails if it disagrees
                // — this is what CI and Docker builds should run

// Auditing and updating deliberately
npm outdated
npm audit
npm audit fix                  // patch-level only
npm update zod                 // within the declared range
npm install zod@4              // a deliberate major, with a changelog read

// pnpm and yarn solve the same problem; pnpm additionally hard-links
// a shared store, which is much faster and disk-cheaper in a monorepo.

// Before adding, check:
//   - Is it maintained? Last publish, open issue count, single maintainer?
//   - How big is it?  bundlephobia.com, or:
npx source-map-explorer .next/static/chunks/*.js
//   - How many transitive dependencies does it drag in?
npm ls --all | wc -l
//   - Could 10 lines of your own code do it?

// Things that no longer need a package:
//   fetch          (was axios)
//   structuredClone (was lodash.clonedeep)
//   crypto.randomUUID (was uuid)
//   Intl.NumberFormat / Intl.DateTimeFormat (was moment)
//   Array.prototype.at, groupBy, Object.groupBy

// left-pad and event-stream are the standard cautionary tales:
// every dependency is code you ship but did not review, from a
// maintainer you do not know.