Skip to main content

Node.js Package Manager (NPM) - Complete Guide to Package Management

NPM (Node Package Manager) is the default package manager for Node.js. It's the world's largest software registry, containing over 1.5 million packages. NPM helps you manage dependencies, scripts, and project configuration in your Node.js applications.

What is NPM?​

NPM is a package manager that:

  • Manages project dependencies
  • Provides a registry of reusable code packages
  • Handles package installation and updates
  • Manages project scripts and configuration
  • Enables package publishing and sharing

Key Features​

  • Package Registry: Access to millions of open-source packages
  • Dependency Management: Automatic dependency resolution
  • Script Management: Run custom scripts and commands
  • Version Control: Semantic versioning support
  • Security: Vulnerability scanning and audit features
  • Workspaces: Manage multiple packages in a single repository

NPM Installation​

NPM comes bundled with Node.js, so if you have Node.js installed, you already have NPM.

Check NPM Version​

npm --version
# or
npm -v

Update NPM​

# Update NPM to the latest version
npm install -g npm@latest

# Update to a specific version
npm install -g [email protected]

Package.json - Project Configuration​

The package.json file is the heart of any Node.js project. It contains metadata about your project and its dependencies.

Creating package.json​

# Initialize a new project
npm init

# Initialize with default values
npm init -y

# Initialize with specific values
npm init --scope=@mycompany

package.json Structure​

{
  "name": "my-nodejs-app",
  "version": "1.0.0",
  "description": "A sample Node.js application",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "test": "jest",
    "dev": "nodemon index.js"
  },
  "keywords": ["nodejs", "express", "api"],
  "author": "Your Name <[email protected]>",
  "license": "MIT",
  "dependencies": {
    "express": "^4.18.2",
    "lodash": "^4.17.21"
  },
  "devDependencies": {
    "nodemon": "^3.0.1",
    "jest": "^29.5.0"
  },
  "engines": {
    "node": ">=14.0.0",
    "npm": ">=6.0.0"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/username/my-nodejs-app.git"
  },
  "bugs": {
    "url": "https://github.com/username/my-nodejs-app/issues"
  },
  "homepage": "https://github.com/username/my-nodejs-app#readme"
}

Key Fields Explained​

  • name: Package name (must be unique on npm registry)
  • version: Semantic version (major.minor.patch)
  • main: Entry point file
  • scripts: Custom commands you can run with npm run
  • dependencies: Packages required in production
  • devDependencies: Packages required only during development
  • engines: Node.js and npm version requirements

Package Installation​

Installing Packages​

# Install a package locally
npm install express

# Install multiple packages
npm install express lodash moment

# Install a specific version
npm install [email protected]

# Install latest version
npm install express@latest

# Install as dev dependency
npm install --save-dev nodemon

# Install globally
npm install -g nodemon

# Install from GitHub
npm install username/repository

# Install from tarball
npm install https://example.com/package.tgz

Installation Options​

# Save to dependencies (default)
npm install express --save

# Save to devDependencies
npm install jest --save-dev

# Save to optionalDependencies
npm install optional-package --save-optional

# Save exact version (no ^ or ~)
npm install express --save-exact

# Install peer dependencies
npm install react --save-peer

# Install bundled dependencies
npm install bundled-package --save-bundle

Version Ranges​

# Exact version
npm install [email protected]

# Compatible version (^4.18.2 allows 4.x.x)
npm install express@^4.18.2

# Approximately equivalent (~4.18.2 allows 4.18.x)
npm install express@~4.18.2

# Latest version
npm install express@latest

# Latest in major version
npm install express@4

# Latest in minor version
npm install [email protected]

Package Management​

Listing Packages​

# List installed packages
npm list

# List packages in tree format
npm list --depth=0

# List only production dependencies
npm list --prod

# List only dev dependencies
npm list --dev

# List globally installed packages
npm list -g

# List outdated packages
npm outdated

Updating Packages​

# Update all packages
npm update

# Update a specific package
npm update express

# Update to latest version (ignoring semver)
npm install express@latest

# Update all packages to latest
npx npm-check-updates -u
npm install

Removing Packages​

# Remove a package
npm uninstall express

# Remove multiple packages
npm uninstall express lodash

# Remove from devDependencies
npm uninstall --save-dev jest

# Remove globally
npm uninstall -g nodemon

NPM Scripts​

NPM scripts are custom commands defined in the scripts section of package.json.

Basic Scripts​

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

Running Scripts​

# Run a script
npm run start

# Run test script
npm run test

# Run dev script
npm run dev

# Run with arguments
npm run test -- --coverage

# Run multiple scripts
npm run lint && npm run test

Pre and Post Scripts​

{
  "scripts": {
    "prestart": "echo 'Starting application...'",
    "start": "node index.js",
    "poststart": "echo 'Application started!'",
    "pretest": "npm run lint",
    "test": "jest",
    "posttest": "npm run coverage"
  }
}

Advanced Script Examples​

{
  "scripts": {
    "start": "node index.js",
    "start:dev": "NODE_ENV=development nodemon index.js",
    "start:prod": "NODE_ENV=production node index.js",
    "test": "jest",
    "test:watch": "jest --watch",
    "test:coverage": "jest --coverage",
    "build": "webpack --mode production",
    "build:dev": "webpack --mode development",
    "lint": "eslint . --ext .js,.jsx,.ts,.tsx",
    "lint:fix": "eslint . --ext .js,.jsx,.ts,.tsx --fix",
    "format": "prettier --write .",
    "format:check": "prettier --check .",
    "clean": "rimraf dist",
    "prepare": "npm run clean && npm run build",
    "precommit": "npm run lint && npm run test",
    "postinstall": "npm run build"
  }
}

NPM Configuration​

Configuration Commands​

# View all configuration
npm config list

# View specific configuration
npm config get registry

# Set configuration
npm config set registry https://registry.npmjs.org/

# Edit configuration file
npm config edit

# Delete configuration
npm config delete registry

Common Configuration Options​

# Set default registry
npm config set registry https://registry.npmjs.org/

# Set proxy
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

# Set cache directory
npm config set cache /tmp/.npm

# Set global directory
npm config set prefix /usr/local

# Set save exact versions
npm config set save-exact true

# Set save prefix
npm config set save-prefix "~"

# Set init settings
npm config set init-author-name "Your Name"
npm config set init-author-email "[email protected]"
npm config set init-license "MIT"

.npmrc File​

Create an .npmrc file in your project root or home directory:

# .npmrc
registry=https://registry.npmjs.org/
save-exact=true
save-prefix=~
init-author-name=Your Name
[email protected]
init-license=MIT

NPM Workspaces​

NPM workspaces allow you to manage multiple packages in a single repository.

Setting Up Workspaces​

{
  "name": "my-workspace",
  "version": "1.0.0",
  "workspaces": [
    "packages/*",
    "apps/*"
  ]
}

Workspace Commands​

# Install dependencies for all workspaces
npm install

# Install package in specific workspace
npm install express --workspace=packages/api

# Run script in all workspaces
npm run test --workspaces

# Run script in specific workspace
npm run test --workspace=packages/api

# List all workspaces
npm ls --workspaces

Package Publishing​

Preparing for Publishing​

# Login to npm
npm login

# Check if package name is available
npm view package-name

# Test package locally
npm pack

# Publish package
npm publish

# Publish with specific tag
npm publish --tag beta

# Publish to specific registry
npm publish --registry https://custom-registry.com/

Package Publishing Checklist​

  1. Update version in package.json
  2. Run tests to ensure everything works
  3. Update README.md with proper documentation
  4. Add proper keywords for discoverability
  5. Set correct license and author information
  6. Test package locally with npm pack
  7. Publish with npm publish

Version Management​

# Patch version (1.0.0 -> 1.0.1)
npm version patch

# Minor version (1.0.0 -> 1.1.0)
npm version minor

# Major version (1.0.0 -> 2.0.0)
npm version major

# Prerelease version
npm version prerelease --preid=beta

# Version with custom message
npm version patch -m "Fix critical bug"

Security and Auditing​

Security Audit​

# Audit dependencies for vulnerabilities
npm audit

# Fix vulnerabilities automatically
npm audit fix

# Fix vulnerabilities with breaking changes
npm audit fix --force

# Audit specific package
npm audit express

Security Best Practices​

# Use exact versions for critical dependencies
npm install [email protected] --save-exact

# Regularly update dependencies
npm update

# Use npm ci for production builds
npm ci

# Lock dependency versions
npm shrinkwrap

NPM Alternatives​

Yarn​

# Install Yarn
npm install -g yarn

# Yarn commands
yarn add express
yarn add --dev jest
yarn install
yarn start

PNPM​

# Install PNPM
npm install -g pnpm

# PNPM commands
pnpm add express
pnpm add -D jest
pnpm install
pnpm start

Best Practices​

Dependency Management​

{
  "dependencies": {
    "express": "^4.18.2",
    "lodash": "^4.17.21"
  },
  "devDependencies": {
    "jest": "^29.5.0",
    "nodemon": "^3.0.1"
  },
  "peerDependencies": {
    "react": ">=16.8.0"
  },
  "optionalDependencies": {
    "fsevents": "^2.3.2"
  }
}

Script Organization​

{
  "scripts": {
    "start": "node index.js",
    "dev": "nodemon index.js",
    "test": "jest",
    "test:watch": "jest --watch",
    "lint": "eslint .",
    "lint:fix": "eslint . --fix",
    "build": "webpack --mode production",
    "clean": "rimraf dist",
    "prepare": "npm run clean && npm run build"
  }
}

Package.json Optimization​

{
  "name": "my-package",
  "version": "1.0.0",
  "description": "Clear description of what the package does",
  "main": "index.js",
  "files": [
    "index.js",
    "lib/",
    "README.md"
  ],
  "keywords": [
    "nodejs",
    "express",
    "api",
    "web"
  ],
  "author": "Your Name <[email protected]>",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/username/my-package.git"
  },
  "bugs": {
    "url": "https://github.com/username/my-package/issues"
  },
  "homepage": "https://github.com/username/my-package#readme",
  "engines": {
    "node": ">=14.0.0",
    "npm": ">=6.0.0"
  }
}

Troubleshooting​

Common Issues​

  1. Permission Errors

    # Fix npm permissions
    sudo chown -R $(whoami) ~/.npm

    # Or use a different directory
    mkdir ~/.npm-global
    npm config set prefix '~/.npm-global'

  2. Cache Issues

    # Clear npm cache
    npm cache clean --force

    # Verify cache
    npm cache verify

  3. Network Issues

    # Set registry
    npm config set registry https://registry.npmjs.org/

    # Set proxy
    npm config set proxy http://proxy.company.com:8080

  4. Version Conflicts

    # Check for conflicts
    npm ls

    # Resolve conflicts
    npm install --legacy-peer-deps

Next Steps​

Now that you've mastered NPM, you're ready to:

  1. Node.js - Callbacks Concept - Understand callback functions
  2. Node.js - Upload Files - Learn file upload handling
  3. Node.js - Send an Email - Implement email functionality
  4. Node.js - Events - Learn event-driven programming

NPM Mastery Complete! You now understand package management, dependency handling, and project configuration. NPM is essential for any Node.js development workflow!