npm - Node Package Manager

calendarDec 12, 2024 Β· 9 min read Β· pkg-knowhow npm nodejs javascript  Β·
Share on: linkedincopy

Essential npm commands for Node.js package management. Quick reference for daily development tasks.

Installation & Setup

 1# Check npm version
 2npm --version
 3npm -v
 4
 5# Update npm
 6npm install -g npm@latest
 7
 8# Initialize new project
 9npm init
10npm init -y  # Skip prompts, use defaults
11
12# Initialize with specific fields
13npm init --scope=@myorg

Installing Packages

 1# Install package (adds to dependencies)
 2npm install <package>
 3npm i <package>
 4
 5# Install specific version
 6npm install <package>@1.2.3
 7npm install <package>@latest
 8npm install <package>@next
 9
10# Install as dev dependency
11npm install --save-dev <package>
12npm install -D <package>
13
14# Install globally
15npm install --global <package>
16npm install -g <package>
17
18# Install from package.json
19npm install
20npm i
21
22# Install from package-lock.json (exact versions)
23npm ci  # Clean install - faster, for CI/CD

Common Packages:

 1# TypeScript
 2npm i -D typescript @types/node
 3
 4# React
 5npm i react react-dom
 6npm i -D @types/react @types/react-dom
 7
 8# Express
 9npm i express
10npm i -D @types/express
11
12# Testing
13npm i -D jest @types/jest
14npm i -D vitest

Uninstalling Packages

 1# Uninstall package
 2npm uninstall <package>
 3npm un <package>
 4npm remove <package>
 5npm rm <package>
 6
 7# Uninstall dev dependency
 8npm uninstall --save-dev <package>
 9npm un -D <package>
10
11# Uninstall globally
12npm uninstall --global <package>
13npm un -g <package>

Updating Packages

 1# Check for outdated packages
 2npm outdated
 3
 4# Update package to latest version
 5npm update <package>
 6npm up <package>
 7
 8# Update all packages
 9npm update
10
11# Update to latest (ignoring semver)
12npm install <package>@latest
13
14# Interactive update (with npm-check-updates)
15npx npm-check-updates
16npx ncu -u  # Update package.json
17npm install  # Install updated versions

Listing Packages

 1# List installed packages
 2npm list
 3npm ls
 4
 5# List top-level packages only
 6npm list --depth=0
 7npm ls --depth=0
 8
 9# List globally installed packages
10npm list -g --depth=0
11
12# List specific package
13npm list <package>
14
15# List outdated packages
16npm outdated

Scripts

 1// package.json
 2{
 3  "scripts": {
 4    "dev": "vite",
 5    "build": "tsc && vite build",
 6    "preview": "vite preview",
 7    "test": "vitest",
 8    "lint": "eslint . --ext ts,tsx",
 9    "format": "prettier --write \"src/**/*.{ts,tsx}\"",
10    "clean": "rm -rf dist node_modules"
11  }
12}

 1# Run script
 2npm run <script>
 3npm run dev
 4npm run build
 5
 6# Special scripts (no "run" needed)
 7npm start   # Runs "start" script
 8npm test    # Runs "test" script
 9npm stop    # Runs "stop" script
10
11# Pass arguments to script
12npm run test -- --watch
13npm run build -- --mode production
14
15# List available scripts
16npm run

Package Information

 1# View package info
 2npm info <package>
 3npm view <package>
 4
 5# View specific field
 6npm info <package> version
 7npm info <package> versions  # All versions
 8npm info <package> dependencies
 9
10# View package homepage
11npm home <package>
12
13# View package repository
14npm repo <package>
15
16# View package bugs
17npm bugs <package>
18
19# View package documentation
20npm docs <package>

Publishing

 1# Login to npm
 2npm login
 3
 4# Check who you're logged in as
 5npm whoami
 6
 7# Publish package
 8npm publish
 9
10# Publish with tag
11npm publish --tag beta
12
13# Publish scoped package (public)
14npm publish --access public
15
16# Unpublish package (within 72 hours)
17npm unpublish <package>@<version>
18
19# Deprecate package version
20npm deprecate <package>@<version> "Use version X instead"

Configuration

 1# View all config
 2npm config list
 3npm config ls
 4
 5# Get specific config
 6npm config get registry
 7npm config get prefix
 8
 9# Set config
10npm config set registry https://registry.npmjs.org/
11npm config set init-author-name "Your Name"
12npm config set init-license "MIT"
13
14# Delete config
15npm config delete <key>
16
17# Edit config file
18npm config edit
19
20# Set registry for scoped packages
21npm config set @myorg:registry https://npm.pkg.github.com

Common Config:

 1# Set default save exact versions
 2npm config set save-exact true
 3
 4# Set default save prefix (^ or ~)
 5npm config set save-prefix "~"
 6
 7# Set npm cache location
 8npm config set cache /path/to/cache
 9
10# Disable package-lock.json
11npm config set package-lock false  # Not recommended

Cache Management

 1# View cache location
 2npm config get cache
 3
 4# Verify cache
 5npm cache verify
 6
 7# Clean cache
 8npm cache clean --force
 9
10# View cache size
11du -sh $(npm config get cache)  # Unix

Workspaces (Monorepo)

1// package.json (root)
2{
3  "name": "my-monorepo",
4  "private": true,
5  "workspaces": [
6    "packages/*",
7    "apps/*"
8  ]
9}

 1# Install all workspace dependencies
 2npm install
 3
 4# Run script in specific workspace
 5npm run build --workspace=packages/app1
 6npm run build -w packages/app1
 7
 8# Run script in all workspaces
 9npm run build --workspaces
10npm run build -ws
11
12# Add dependency to specific workspace
13npm install lodash --workspace=packages/app1
14npm i lodash -w packages/app1
15
16# List workspaces
17npm ls --workspaces

Workspace Structure:

 1my-monorepo/
 2β”œβ”€β”€ package.json
 3β”œβ”€β”€ packages/
 4β”‚   β”œβ”€β”€ app1/
 5β”‚   β”‚   └── package.json
 6β”‚   └── app2/
 7β”‚       └── package.json
 8└── apps/
 9    └── web/
10        └── package.json

Security

 1# Audit packages for vulnerabilities
 2npm audit
 3
 4# Audit and fix automatically
 5npm audit fix
 6
 7# Audit and fix (including breaking changes)
 8npm audit fix --force
 9
10# View audit report in browser
11npm audit --json | npm-audit-html
12
13# Install specific security update
14npm update <package> --depth 2

Troubleshooting

 1# Clear npm cache
 2npm cache clean --force
 3
 4# Remove node_modules and reinstall
 5rm -rf node_modules package-lock.json
 6npm install
 7
 8# Rebuild native modules
 9npm rebuild
10
11# Check for issues
12npm doctor
13
14# Verbose logging
15npm install --verbose
16npm install --loglevel verbose
17
18# Debug mode
19npm install --dd

Version Management

 1# Bump version
 2npm version patch  # 1.0.0 -> 1.0.1
 3npm version minor  # 1.0.0 -> 1.1.0
 4npm version major  # 1.0.0 -> 2.0.0
 5
 6# Bump version with tag
 7npm version patch -m "Bump version to %s"
 8
 9# Bump prerelease version
10npm version prerelease  # 1.0.0 -> 1.0.1-0
11npm version prepatch    # 1.0.0 -> 1.0.1-0
12npm version preminor    # 1.0.0 -> 1.1.0-0
13npm version premajor    # 1.0.0 -> 2.0.0-0

Useful npm Packages

 1# npx - Run packages without installing
 2npx create-react-app my-app
 3npx create-vite my-app
 4npx tsc --init
 5
 6# npm-check-updates - Update package.json
 7npx npm-check-updates
 8npx ncu -u
 9
10# http-server - Simple HTTP server
11npx http-server
12
13# nodemon - Auto-restart on file changes
14npm i -D nodemon
15
16# concurrently - Run multiple commands
17npm i -D concurrently
18# "dev": "concurrently \"npm run server\" \"npm run client\""
19
20# cross-env - Set environment variables cross-platform
21npm i -D cross-env
22# "build": "cross-env NODE_ENV=production webpack"

package.json Fields

 1{
 2  "name": "my-package",
 3  "version": "1.0.0",
 4  "description": "My awesome package",
 5  "main": "dist/index.js",
 6  "types": "dist/index.d.ts",
 7  "scripts": {
 8    "dev": "vite",
 9    "build": "tsc && vite build",
10    "test": "vitest"
11  },
12  "keywords": ["awesome", "package"],
13  "author": "Your Name <you@example.com>",
14  "license": "MIT",
15  "repository": {
16    "type": "git",
17    "url": "https://github.com/user/repo.git"
18  },
19  "bugs": {
20    "url": "https://github.com/user/repo/issues"
21  },
22  "homepage": "https://github.com/user/repo#readme",
23  "dependencies": {
24    "react": "^18.2.0"
25  },
26  "devDependencies": {
27    "typescript": "^5.0.0"
28  },
29  "peerDependencies": {
30    "react": ">=16.8.0"
31  },
32  "engines": {
33    "node": ">=18.0.0",
34    "npm": ">=9.0.0"
35  },
36  "files": [
37    "dist",
38    "README.md"
39  ]
40}

Semver (Semantic Versioning)

1MAJOR.MINOR.PATCH
2  1  .  2  .  3
3
4MAJOR: Breaking changes
5MINOR: New features (backward compatible)
6PATCH: Bug fixes (backward compatible)

Version Ranges:

 1{
 2  "dependencies": {
 3    "package1": "1.2.3",      // Exact version
 4    "package2": "^1.2.3",     // ^1.2.3 <= version < 2.0.0
 5    "package3": "~1.2.3",     // ~1.2.3 <= version < 1.3.0
 6    "package4": ">=1.2.3",    // Greater than or equal
 7    "package5": "1.2.x",      // 1.2.0 <= version < 1.3.0
 8    "package6": "*",          // Any version (avoid!)
 9    "package7": "latest"      // Latest version (avoid!)
10  }
11}

Caret (^) vs Tilde (~):

  • ^1.2.3: Compatible with 1.2.3 (allows minor and patch updates)
  • ~1.2.3: Approximately 1.2.3 (allows patch updates only)

Common Gotchas

1. Node Version Mismatch

 1# Check Node version
 2node --version
 3
 4# Use nvm to switch versions
 5nvm install 18
 6nvm use 18
 7
 8# Or use .nvmrc file
 9echo "18" > .nvmrc
10nvm use

2. Permission Errors (Global Install)

 1# ❌ Don't use sudo with npm
 2sudo npm install -g <package>
 3
 4# βœ… Fix npm permissions
 5mkdir ~/.npm-global
 6npm config set prefix '~/.npm-global'
 7# Add to ~/.bashrc or ~/.zshrc:
 8export PATH=~/.npm-global/bin:$PATH
 9
10# Or use nvm (recommended)

3. package-lock.json Conflicts

1# After merging, regenerate lock file
2rm package-lock.json
3npm install
4
5# Or use npm ci in CI/CD
6npm ci  # Fails if package.json and lock file don't match

4. Peer Dependency Warnings

1# Install peer dependencies manually
2npm install <peer-dependency>
3
4# Or use --legacy-peer-deps flag
5npm install --legacy-peer-deps
6
7# Or use --force (not recommended)
8npm install --force

Create and Publish Package

Package Structure

 1my-package/
 2β”œβ”€β”€ src/
 3β”‚   └── index.js
 4β”œβ”€β”€ test/
 5β”‚   └── index.test.js
 6β”œβ”€β”€ package.json
 7β”œβ”€β”€ README.md
 8β”œβ”€β”€ LICENSE
 9β”œβ”€β”€ .gitignore
10└── .npmignore

Initialize Package

1# Create package.json
2npm init
3
4# Or with defaults
5npm init -y
6
7# Or use npm init with scope
8npm init --scope=@myorg

package.json

 1{
 2  "name": "my-package",
 3  "version": "1.0.0",
 4  "description": "A useful package",
 5  "main": "dist/index.js",
 6  "types": "dist/index.d.ts",
 7  "scripts": {
 8    "build": "tsc",
 9    "test": "jest",
10    "prepublishOnly": "npm run build && npm test"
11  },
12  "keywords": ["utility", "helper"],
13  "author": "Your Name <email@example.com>",
14  "license": "MIT",
15  "repository": {
16    "type": "git",
17    "url": "https://github.com/username/my-package.git"
18  },
19  "bugs": {
20    "url": "https://github.com/username/my-package/issues"
21  },
22  "homepage": "https://github.com/username/my-package#readme",
23  "files": [
24    "dist",
25    "README.md",
26    "LICENSE"
27  ],
28  "dependencies": {},
29  "devDependencies": {
30    "typescript": "^5.0.0",
31    "jest": "^29.0.0"
32  },
33  "engines": {
34    "node": ">=16.0.0"
35  }
36}

Build Package

 1# Build (if using TypeScript)
 2npm run build
 3
 4# Test
 5npm test
 6
 7# Check what will be published
 8npm pack --dry-run
 9
10# Create tarball
11npm pack

Publish to npm Registry

 1# Create npm account at https://www.npmjs.com/signup
 2
 3# Login
 4npm login
 5
 6# Publish package
 7npm publish
 8
 9# Publish scoped package (public)
10npm publish --access public
11
12# Publish scoped package (private, requires paid account)
13npm publish --access restricted
14
15# Publish with tag
16npm publish --tag beta
17
18# Unpublish (within 72 hours)
19npm unpublish my-package@1.0.0
20
21# Deprecate version
22npm deprecate my-package@1.0.0 "Use version 2.0.0 instead"

Versioning

 1# Update version
 2npm version patch  # 1.0.0 -> 1.0.1
 3npm version minor  # 1.0.0 -> 1.1.0
 4npm version major  # 1.0.0 -> 2.0.0
 5
 6# Update and publish
 7npm version patch && npm publish
 8
 9# Pre-release versions
10npm version prepatch  # 1.0.0 -> 1.0.1-0
11npm version preminor  # 1.0.0 -> 1.1.0-0
12npm version premajor  # 1.0.0 -> 2.0.0-0

Private npm Registry

Using Verdaccio (Self-hosted)

 1# Install Verdaccio
 2npm install -g verdaccio
 3
 4# Run Verdaccio
 5verdaccio
 6
 7# Configure npm to use Verdaccio
 8npm set registry http://localhost:4873/
 9
10# Create user
11npm adduser --registry http://localhost:4873/
12
13# Publish to Verdaccio
14npm publish --registry http://localhost:4873/
15
16# Install from Verdaccio
17npm install my-package --registry http://localhost:4873/

Using GitHub Packages

1# Create .npmrc in project
2echo "@myorg:registry=https://npm.pkg.github.com" > .npmrc
3
4# Login to GitHub Packages
5npm login --scope=@myorg --registry=https://npm.pkg.github.com
6
7# Publish
8npm publish

Using Artifactory/Nexus

1# Configure registry
2npm config set registry https://artifactory.example.com/api/npm/npm-local/
3
4# Login
5npm login --registry=https://artifactory.example.com/api/npm/npm-local/
6
7# Publish
8npm publish --registry=https://artifactory.example.com/api/npm/npm-local/

.npmignore

 1# .npmignore
 2src/
 3test/
 4*.test.js
 5.git
 6.gitignore
 7.env
 8node_modules/
 9coverage/
10.DS_Store

Related Snippets