Node.js NPM

Node.js npm: Managing Packages, Scripts, and Versions

npm (Node Package Manager) is the default package manager bundled with Node.js for installing open-source libraries, tracking dependency versions, and running project task scripts. Every npm-managed project relies on two core files: package.json and package-lock.json.

Installing Packages and package.json Sections

When you install a library with npm install, npm updates package.json and writes exact resolved versions into package-lock.json so every teammate and CI server installs identical code.

• dependencies (npm install express): Runtime packages required in production.
• devDependencies (npm install -D vitest eslint): Tools needed only during local coding, testing, or bundling.
• scripts: Shortcut commands run with npm run <name> (or npm test / npm start).

{
  "name": "orders-api",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "dev": "node --watch src/server.js",
    "start": "node src/server.js",
    "test": "node --test"
  },
  "dependencies": {
    "zod": "^3.23.8"
  },
  "devDependencies": {
    "eslint": "^9.0.0"
  }
}

Understanding Semantic Versioning (^ vs ~) and npm ci

Semantic versioning follows MAJOR.MINOR.PATCH (for example, 3.23.8):

• ^3.23.8 (Caret): Allows minor and patch updates below version 4.0.0 that should remain backwards-compatible.
• ~3.23.8 (Tilde): Allows patch bugfixes only below version 3.24.0.

In automated deployments and CI pipelines, run npm ci instead of npm install. npm ci deletes any stale node_modules folder and installs cleanly straight from package-lock.json without modifying lockfile entries, guaranteeing reproducible builds on every server.

Everyday npm CLI Commands

Learn these core commands to manage dependencies, run security audits, and execute local scripts cleanly:

• npm install express: Installs a runtime dependency and saves it under dependencies.
• npm install -D vitest: Installs a development-only tool such as ESLint or Vitest under devDependencies.
• npm outdated & npm update: Inspects available semver-compatible updates and updates lockfile versions cleanly.
• npm audit: Scans your dependency tree against known security advisories and flags vulnerable packages before deployment.
• npm exec / npx: Runs a package binary directly from local node_modules/.bin or downloads one temporarily without polluting global tools.

Common Mistakes to Avoid

• Deleting or .gitignore-ing package-lock.json in apps: Always commit package-lock.json for applications so production deploys never pull unexpected breaking dependency updates.
• Committing node_modules/ to Git: node_modules contains thousands of files and OS-specific binaries. Add node_modules/ to .gitignore.
• Installing random packages without checking maintenance: Check weekly downloads, license, and run npm audit regularly to spot known security vulnerabilities.

Frequently Asked Questions

What is npx used for?

npx downloads and runs a package CLI binary (like npx create-next-app@latest) once without installing it permanently into your global system folder.

How do I run a script defined in package.json?

Run npm run dev or npm run build matching the script key in package.json. Built-in lifecycle names like start and test also work without run (npm test).

How do I install only production dependencies on a server?

Run npm ci --omit=dev so test runners and linters are skipped in production containers.