NPM and Package Management

What is NPM?

NPM serves three main purposes:

• Package Registry: The world's largest software registry with over 2 million packages
• Command-line Tool: A CLI for managing packages in your projects
• Website: npmjs.com for discovering packages

Getting Started with NPM

Checking NPM Installation

# Check if NPM is installed
npm --version

# Check Node.js version (NPM comes with Node.js)
node --version

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

Initializing a New Project

# Create a new directory for your project
mkdir my-awesome-project
cd my-awesome-project

# Initialize NPM (interactive)
npm init

# Initialize with defaults
npm init -y

# Initialize with specific settings
npm init --scope=@mycompany --yes

The Interactive npm init Process

$ npm init
This utility will walk you through creating a package.json file.
It only covers the most common items, and tries to guess sensible defaults.

package name: (my-awesome-project) 
version: (1.0.0) 
description: A demo project for learning NPM
entry point: (index.js) 
test command: jest
git repository: https://github.com/username/my-awesome-project
keywords: demo, npm, learning
author: Your Name 
license: (ISC) MIT

About to write to /path/to/my-awesome-project/package.json:

{
  "name": "my-awesome-project",
  "version": "1.0.0",
  "description": "A demo project for learning NPM",
  "main": "index.js",
  "scripts": {
    "test": "jest"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/username/my-awesome-project.git"
  },
  "keywords": [
    "demo",
    "npm",
    "learning"
  ],
  "author": "Your Name ",
  "license": "MIT"
}

Is this OK? (yes)

Understanding package.json

The package.json file is like a recipe card for your project. It lists all ingredients (dependencies) and instructions (scripts) needed to make your project work.

{
  "name": "my-awesome-project",
  "version": "1.0.0",
  "description": "A demo project for learning NPM",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "dev": "nodemon index.js",
    "test": "jest",
    "build": "webpack --mode production",
    "lint": "eslint ."
  },
  "keywords": ["demo", "npm", "learning"],
  "author": "Your Name ",
  "license": "MIT",
  "dependencies": {
    "express": "^4.18.2",
    "lodash": "^4.17.21"
  },
  "devDependencies": {
    "jest": "^29.5.0",
    "nodemon": "^2.0.22",
    "eslint": "^8.38.0"
  },
  "engines": {
    "node": ">=14.0.0",
    "npm": ">=6.0.0"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/username/my-awesome-project.git"
  },
  "bugs": {
    "url": "https://github.com/username/my-awesome-project/issues"
  },
  "homepage": "https://github.com/username/my-awesome-project#readme"
}

Key Fields Explained

Semantic Versioning (SemVer)

NPM uses semantic versioning to manage package versions. Think of it like software DNA - Major.Minor.Patch

Version Range Syntax

// Exact version
"lodash": "4.17.21"

// Patch updates allowed (bug fixes)
"lodash": "~4.17.21"    // 4.17.x

// Minor updates allowed (new features)
"lodash": "^4.17.21"    // 4.x.x

// Any version
"lodash": "*"

// Version ranges
"lodash": ">=4.0.0 <5.0.0"
"lodash": "4.x"
"lodash": "4.17.x"

// Multiple ranges
"lodash": ">=1.2.3 <1.3.0 || >=2.0.0 <3.0.0"

Real-World Examples

// React project dependencies
{
  "dependencies": {
    "react": "^18.2.0",      // Allow minor updates
    "react-dom": "^18.2.0",  // Keep in sync with react
    "axios": "^1.4.0",       // Latest features welcome
    "lodash": "~4.17.21"     // Only bug fixes
  },
  "devDependencies": {
    "@types/react": "^18.2.0",
    "typescript": "^5.0.0",
    "jest": "^29.5.0"
  }
}

Installing Packages

Basic Installation Commands

# Install a package and add to dependencies
npm install express
npm i express  # shorthand

# Install and add to devDependencies
npm install --save-dev jest
npm i -D jest  # shorthand

# Install globally
npm install -g typescript
npm i -g typescript

# Install specific version
npm install react@17.0.2

# Install from Git repository
npm install git+https://github.com/user/repo.git

# Install from local folder
npm install ../my-local-package

Understanding Installation Process

The node_modules Directory

The node_modules directory is like a library where all your project's dependencies live. It can get quite large!

my-awesome-project/
├── node_modules/
│   ├── express/
│   │   ├── lib/
│   │   ├── index.js
│   │   └── package.json
│   ├── lodash/
│   │   ├── lodash.js
│   │   └── package.json
│   └── ... (hundreds more)
├── src/
│   └── index.js
├── package.json
└── package-lock.json

Important Notes About node_modules

• Never commit node_modules to version control (add to .gitignore)
• Can be safely deleted and recreated with npm install
• Contains all dependencies and their dependencies (nested)
• Takes up significant disk space

Example .gitignore

# Dependencies
node_modules/
npm-debug.log*

# Environment variables
.env
.env.local

# Build output
dist/
build/

# IDE files
.vscode/
.idea/

# OS files
.DS_Store
Thumbs.db

package-lock.json

The package-lock.json is like a detailed receipt of exactly what was installed. It ensures everyone on your team has identical dependencies.

{
  "name": "my-awesome-project",
  "version": "1.0.0",
  "lockfileVersion": 2,
  "requires": true,
  "packages": {
    "": {
      "name": "my-awesome-project",
      "version": "1.0.0",
      "dependencies": {
        "express": "^4.18.2"
      }
    },
    "node_modules/express": {
      "version": "4.18.2",
      "resolved": "https://registry.npmjs.org/express/-/express-4.18.2.tgz",
      "integrity": "sha512-...",
      "dependencies": {
        "accepts": "~1.3.8",
        "array-flatten": "1.1.1",
        // ... more dependencies
      }
    }
    // ... more packages
  }
}

Why package-lock.json Matters

• Ensures consistent installations across different machines
• Locks specific versions of all dependencies
• Improves installation speed by providing exact dependency tree
• Should be committed to version control

NPM Scripts

NPM scripts are like shortcuts or recipes for common tasks in your project. They're defined in package.json and can be run with npm run.

{
  "scripts": {
    "start": "node server.js",
    "dev": "nodemon server.js",
    "test": "jest",
    "test:watch": "jest --watch",
    "build": "webpack --mode production",
    "build:dev": "webpack --mode development",
    "lint": "eslint .",
    "lint:fix": "eslint . --fix",
    "format": "prettier --write .",
    "prepare": "husky install",
    "prepublishOnly": "npm test && npm run build",
    "deploy": "npm run build && firebase deploy"
  }
}

Running Scripts

# Run predefined scripts
npm start         # Special: no 'run' needed
npm test          # Special: no 'run' needed
npm run build     # Custom scripts need 'run'
npm run dev

# Pass arguments to scripts
npm run test -- --coverage
npm run build -- --watch

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

# Pre and Post scripts
# pretest runs before test
# posttest runs after test
{
  "scripts": {
    "pretest": "npm run lint",
    "test": "jest",
    "posttest": "echo 'Tests complete!'"
  }
}

Script Lifecycle

Updating and Managing Dependencies

Checking for Updates

# Check for outdated packages
npm outdated

# Output example:
Package    Current  Wanted  Latest  Location
express    4.17.1   4.17.3  4.18.2  my-project
lodash     4.17.20  4.17.20 4.17.21 my-project
jest       27.0.0   27.5.1  29.5.0  my-project

# Check globally installed packages
npm outdated -g

Updating Packages

# Update all packages to 'wanted' version
npm update

# Update specific package
npm update express

# Update to latest version (may include breaking changes)
npm install express@latest

# Update all packages to latest (be careful!)
npm install lodash@latest express@latest

# Interactive update with npm-check-updates
npx npm-check-updates -u
npm install

Removing Packages

# Remove a package
npm uninstall express
npm rm express  # shorthand

# Remove and update package.json
npm uninstall express --save

# Remove dev dependency
npm uninstall jest --save-dev

# Remove global package
npm uninstall -g typescript

Auditing Dependencies

NPM includes security auditing to help identify vulnerabilities in your dependencies.

# Run security audit
npm audit

# Output example:
found 7 vulnerabilities (2 low, 3 moderate, 2 high)

# Fix automatically where possible
npm audit fix

# Fix including major updates (breaking changes)
npm audit fix --force

# Get detailed audit report
npm audit --json

# Only audit production dependencies
npm audit --production

Sample Audit Report

┌───────────────┬──────────────────────────────────────┐
│ High          │ Prototype Pollution                   │
├───────────────┼──────────────────────────────────────┤
│ Package       │ lodash                               │
├───────────────┼──────────────────────────────────────┤
│ Dependency of │ express                              │
├───────────────┼──────────────────────────────────────┤
│ Path          │ express > lodash                     │
├───────────────┼──────────────────────────────────────┤
│ More info     │ https://npmjs.com/advisories/1523    │
└───────────────┴──────────────────────────────────────┘

Creating Your Own Package

Creating an NPM package is like packaging a gift - you prepare your code, wrap it properly, and share it with the world!

Basic Package Structure

my-package/
├── src/
│   └── index.js
├── test/
│   └── index.test.js
├── .gitignore
├── .npmignore
├── LICENSE
├── README.md
└── package.json

Essential package.json Fields

{
  "name": "@myusername/my-package",
  "version": "1.0.0",
  "description": "A fantastic utility package",
  "main": "src/index.js",
  "files": [
    "src",
    "README.md"
  ],
  "scripts": {
    "test": "jest",
    "prepublishOnly": "npm test"
  },
  "keywords": ["utility", "helper", "awesome"],
  "author": "Your Name ",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/username/my-package.git"
  },
  "bugs": {
    "url": "https://github.com/username/my-package/issues"
  },
  "homepage": "https://github.com/username/my-package#readme"
}

Example Package Code

// src/index.js
function formatDate(date, format = 'YYYY-MM-DD') {
  const d = new Date(date);
  const year = d.getFullYear();
  const month = String(d.getMonth() + 1).padStart(2, '0');
  const day = String(d.getDate()).padStart(2, '0');
  
  return format
    .replace('YYYY', year)
    .replace('MM', month)
    .replace('DD', day);
}

function capitalize(str) {
  return str.charAt(0).toUpperCase() + str.slice(1);
}

module.exports = {
  formatDate,
  capitalize
};

Publishing to NPM

Publishing Process

Publishing Commands

# Login to NPM
npm login

# Check who you're logged in as
npm whoami

# Publish package
npm publish

# Publish with public access (for scoped packages)
npm publish --access=public

# Publish beta version
npm publish --tag beta

# Update version and publish
npm version patch  # 1.0.0 -> 1.0.1
npm version minor  # 1.0.0 -> 1.1.0
npm version major  # 1.0.0 -> 2.0.0
npm publish

# Unpublish (use with caution!)
npm unpublish my-package@1.0.0

Best Practices

Dependency Management

• Use exact versions for critical dependencies
• Regularly audit and update dependencies
• Minimize dependency count when possible
• Use package-lock.json for consistency
• Separate dev and production dependencies properly

Package Creation

• Write comprehensive README documentation
• Include TypeScript definitions if applicable
• Follow semantic versioning strictly
• Test thoroughly before publishing
• Use .npmignore to exclude unnecessary files

Security Considerations

• Never publish sensitive information (API keys, passwords)
• Regularly run npm audit
• Be cautious with packages requiring many permissions
• Verify package names to avoid typosquatting

Practice Exercises

Exercise 1: Create a Project

# Create a new project called "todo-cli"
# 1. Initialize npm
# 2. Install these dependencies:
#    - commander (CLI framework)
#    - chalk (Terminal styling)
#    - inquirer (Interactive prompts)
# 3. Create scripts for:
#    - start: runs the CLI
#    - test: runs tests
#    - lint: checks code style

Exercise 2: Package Audit

# Given this package.json:
{
  "dependencies": {
    "express": "4.16.0",
    "lodash": "4.17.4",
    "moment": "2.19.3"
  }
}

# Tasks:
# 1. Check for outdated packages
# 2. Run security audit
# 3. Update packages safely
# 4. Document the changes made

Common NPM Commands Reference

# Project initialization
npm init
npm init -y

# Installing packages
npm install package-name
npm i package-name
npm install --save-dev package-name
npm install --global package-name

# Managing packages
npm update
npm uninstall package-name
npm outdated
npm audit
npm audit fix

# Running scripts
npm start
npm test
npm run script-name

# Publishing
npm login
npm publish
npm version patch/minor/major

# Information
npm ls
npm view package-name
npm docs package-name
npm repo package-name

# Cache management
npm cache clean --force
npm cache verify

Key Takeaways

• NPM is the world's largest software registry
• package.json is the heart of any Node.js project
• Semantic versioning helps manage dependencies safely
• package-lock.json ensures consistent installations
• NPM scripts automate common development tasks
• Regular auditing helps maintain security
• Publishing packages contributes to the JavaScript ecosystem

Additional Resources

• Official NPM Documentation
• Semantic Versioning Specification
• NPM CLI GitHub Repository
• How NPM Works