npm and package.json

Virtually every Node project begins with npm init. The Node.js for Beginners series now introduces npm: the registry, the command-line tool and the manifest file that together define your project. By the end you will read any package.json with confidence, install dependencies deliberately, and use scripts as your project's command menu.

Three things called npm

• The registry — a public database of published packages (express, lodash, jest…) with every version ever released.
• The CLI — the npm command installed with Node that talks to that registry.
• The configuration file — package.json, the manifest every Node project carries.

A package is a folder with a manifest; it can contain a library, a CLI tool, or both. Installing one copies it into node_modules and records the intent in your manifest.

Anatomy of package.json

{
  "name": "todo-api",
  "version": "1.0.0",
  "description": "A tiny to-do REST API",
  "type": "module",
  "main": "src/server.js",
  "scripts": {
    "start": "node src/server.js",
    "dev": "node --watch src/server.js"
  },
  "keywords": ["todo", "api", "express"],
  "license": "MIT",
  "dependencies": {
    "express": "^5.1.0"
  },
  "devDependencies": {
    "nodemon": "^3.1.9"
  }
}

Installing packages

npm init -y                 # create package.json with defaults
npm install express         # add to "dependencies"
npm install --save-dev nodemon   # add to "devDependencies"
npm install                 # install everything from the manifest
npm uninstall express       # remove it and update the manifest

Expected output: each command prints a summary such as added 64 packages in 2s and rewrites package-lock.json. Modern npm saves to dependencies by default — --save is historical.

Version ranges explained

Semantic versioning reads major.minor.patch: breaking changes bump the major, features the minor, fixes the patch. ^ is safe for libraries because minors and patches are promised not to break you; exact pins belong in deployment-critical tools. When you are ready to publish your own package, the same manifest describes it for everyone else — npm publish uploads the folder, and consumers install exactly what your fields promise.

Scripts: your project's command menu

npm run dev
npm test
npm run lint

Expected output: the dev script above starts node --watch src/server.js, prints a watch message, and restarts the server every time you save a file — nodemon's job without the extra dependency (Node 18.11+ ships the flag).

• npm start and npm test are conventional names with built-in shorthand — no run needed.
• Anything else needs npm run <name>.
• Keep scripts portable: a shell script that only works on one OS will bite your teammates.

node_modules and the lock file

node_modules is a local cache of installed packages — delete it freely, npm install rebuilds it. package-lock.json is not deletable: it records the exact resolved version of every package in the tree, so every machine and CI run installs identical code. Commit the lock file; add node_modules to .gitignore. Three commands round out the daily routine: npm outdated shows what has drifted, npm audit reports known vulnerabilities in your tree, and npm ci does a clean, lock-file-exact install — the one CI pipelines should call instead of npm install.

Common mistakes

• Committing node_modules — tens of thousands of files that npm install recreates in seconds.
• Deleting package-lock.json — "it causes conflicts" is backwards; the lock file prevents environment drift.
• Putting dev tools in dependencies — bloats production installs; linters and test runners belong in dev.
• Using * ranges — a surprise major release becomes your surprise outage.
• Running global installs for project tools — each project should declare its own versions so upgrades are deliberate.

Practice checklist

1. Run npm init -y in an empty folder and rewrite the generated fields to describe a real idea.
2. Install one runtime dependency and one dev dependency; confirm which array each landed in.
3. Add a start and a dev script and run both.
4. Read the lock file (just the first 30 lines) and find the resolved version of your dependency.
5. Delete node_modules, restore it with npm install, and prove the app still runs.

Your toolchain is ready — now for the behaviour that defines Node itself. Next: Asynchronous JavaScript in Node.