Comprehensive npm Guide: Managing Packages Effectively

npm (Node Package Manager) is the default package manager for Node.js. It manages dependencies, runs scripts, and publishes packages. This guide covers everything from initialization to security auditing.

Initialization

npm init           # interactive — prompts for name, version, description
npm init -y        # skip prompts, accept all defaults

This creates package.json, which defines your project and its dependencies.

Installing Packages

npm install lodash              # add to dependencies (production)
npm install jest --save-dev     # add to devDependencies (dev only)
npm install                     # install all packages listed in package.json
npm install --production        # install only production dependencies

The --save flag is no longer needed (npm 5+) — all installs are saved by default.

Install a specific version:

npm install lodash@4.17.21
npm install "lodash@^4.0.0"     # install any 4.x compatible version

Understanding version ranges:

• 4.17.21 — exact version
• ^4.17.21 — compatible with 4.x.x (caret: allows minor and patch)
• ~4.17.21 — approximately 4.17.x (tilde: allows only patch updates)
• * — latest version

Updating and Removing Packages

npm update lodash               # update to the latest compatible version
npm update                      # update all packages within range

npm uninstall lodash            # remove from dependencies
npm uninstall jest --save-dev   # remove from devDependencies

Listing Installed Packages

npm list                        # all packages (full tree)
npm list --depth=0              # direct dependencies only
npm list --global               # globally installed packages

npm Scripts

Define reusable commands in package.json:

{
  "scripts": {
    "start": "node index.js",
    "dev": "nodemon index.js",
    "build": "webpack --mode production",
    "test": "jest",
    "test:watch": "jest --watch",
    "lint": "eslint src/",
    "format": "prettier --write src/"
  }
}

Run them with:

npm run dev
npm test          # shorthand for npm run test
npm start         # shorthand for npm run start

Scripts can chain other scripts using && or npm run:

"prebuild": "npm run lint",
"build": "webpack --mode production",
"postbuild": "npm run test"

pre and post hooks run automatically before and after the named script.

Global Packages

Install tools globally to use them from any directory:

npm install -g nodemon         # install globally
npm install -g typescript
npm uninstall -g nodemon       # uninstall global package

npm root -g                    # find global installation directory
npm list -g --depth=0          # list global packages

npx — Run Without Installing

npx runs a package without permanently installing it:

npx create-react-app my-app    # use once, don't pollute global
npx prettier --write .         # run a specific version
npx ts-node script.ts          # run TypeScript directly

Prefer npx for one-off tool invocations.

Security Auditing

npm audit                      # check for known vulnerabilities
npm audit --json               # machine-readable output
npm audit fix                  # automatically fix safe upgrades
npm audit fix --force          # apply all fixes (may include breaking changes)

Run npm audit in CI to catch vulnerable dependencies before they reach production.

package-lock.json

package-lock.json records the exact installed versions of every dependency (direct and transitive). Always commit this file. It ensures every developer and CI environment installs identical packages, regardless of what's published to the npm registry.

npm ci                         # install exact versions from package-lock.json
                               # faster and stricter than npm install (CI use)

Use npm ci in CI/CD pipelines instead of npm install.

Configuration Defaults

Set defaults that pre-fill npm init prompts:

npm config set init-author-name "Your Name"
npm config set init-license "MIT"
npm config get init-author-name
npm config delete init-author-name

Useful Flags

npm install --dry-run          # show what would be installed, without installing
npm install --verbose          # detailed output for debugging
npm install --legacy-peer-deps # bypass peer dependency conflicts (older packages)

Conclusion

The most important npm practices: commit package-lock.json, run npm ci in CI, use npm audit regularly, and prefer npx for one-off tool use. For large monorepos, look at npm workspaces or tools like Turborepo to manage multiple packages in a single repository.