Project A requires Node 16 (legacy)
Project B requires Node 18 (LTS)
Project C requires Node 20 (latest)

Without a version manager, you need:
1. Install one version
2. Work on Project A
3. Uninstall
4. Install another version
5. Work on Project B
6. 😡 This is terrible!

With a version manager (nvm):
nvm use 16   # Switch to Node 16
nvm use 18   # Switch to Node 18
nvm use 20   # Switch to Node 20

NODE.JS VERSION MANAGER (nvm)
═══════════════════════════════

Without nvm:
┌──────────────────────────────────────────┐
│ Global: Node v18.17.0                    │
│                                          │
│  Project A (needs 16) → ❌ Can't run    │
│  Project B (needs 18) → ✅ Works         │
│  Project C (needs 20) → ❌ Can't run    │
└──────────────────────────────────────────┘

With nvm:
┌──────────────────────────────────────────┐
│ nvm list:                                │
│  ➡ v16.20.2 (default)                    │
│     v18.17.0 (LTS)                       │
│     v20.11.0 (latest)                    │
│                                          │
│  Project A: nvm use 16 → ✅      │
│  Project B: nvm use 18 → ✅      │
│  Project C: nvm use 20 → ✅      │
└──────────────────────────────────────────┘

flowchart TD
    Start["Install Node.js"] --> OS{"What OS?"}

    OS -->|"macOS"| MacChoice{"Method?"}
    MacChoice -->|"Recommended"| Brew["brew install node\n(or nvm + brew)"]
    MacChoice -->|"Alternative"| Official["Download .pkg from\nnodejs.org"]

    OS -->|"Windows"| WinChoice{"Method?"}
    WinChoice -->|"Recommended"| NvmWin["nvm-windows\n(version manager)"]
    WinChoice -->|"Simple"| WinInstaller["Download .msi from\nnodejs.org"]
    WinChoice -->|"Dev"| WSL["Install on WSL\n(sudo apt install node)"]

    OS -->|"Linux"| LinuxChoice{"Distro?"}
    LinuxChoice -->|"Ubuntu/Debian"| Nodesource["NodeSource PPA\ncurl -fsSL ... | bash -"]
    LinuxChoice -->|"Any"| NvmInstall["nvm install 20\n(recommended for all)"]

    Brew --> Verify["node --version\nnpm --version"]
    NvmWin --> Verify
    Nodesource --> Verify
    NvmInstall --> Verify
    Official --> Verify
    WinInstaller --> Verify
    WSL --> Verify

    style Start fill:#4f46e5,color:#fff
    style Verify fill:#10b981,color:#fff

Installing Node.js creates:
───────────────────────────

/usr/local/bin/       (or C:\Program Files\nodejs\)
├── node              ← Node.js runtime (V8 + libuv)
├── npm               ← Package manager
├── npx               ← Package runner (Node 14+)
└── corepack          ← Package manager manager (Node 16+)

node is a compiled binary that includes:
- V8 JavaScript engine
- libuv (Event Loop + Thread Pool)
- Node.js built-in modules (compiled in)
- Initialization scripts

The ELF/Mach-O/PE binary is ~80MB on disk.

flowchart LR
    subgraph Nvm["nvm (Node Version Manager)"]
        Installed["~/.nvm/\nversions/node/\n├── v16.20.2/\n├── v18.17.0/\n└── v20.11.0/"]
        Symlink["$NVM_BIN/node →\nselected version"]
        RcFile[".nvmrc file\nin project root"]
    end

    subgraph Shell["Shell Integration"]
        Profile[".bashrc / .zshrc\nsource nvm.sh"]
        Auto["Automatic switch\non cd into project"]
        Path["PATH=$NVM_BIN:$PATH"]
    end

    subgraph Commands["Commands"]
        NvmInstall["nvm install 18"]
        NvmUse["nvm use 18"]
        NvmList["nvm ls"]
        NvmDefault["nvm alias default 18"]
    end

    Commands --> Installed
    NvmUse --> Symlink
    Symlink --> Profile
    RcFile --> Auto

    style Nvm fill:#4f46e5,color:#fff
    style Shell fill:#059669,color:#fff
    style Commands fill:#d97706,color:#fff

flowchart TB
    subgraph Base["Base Setup"]
        Nvm["nvm — Node Version Manager"]
        Node["Node.js LTS (v18 or v20)"]
        Npm["npm — Package Manager"]
    end

    subgraph IDE["Editor Setup"]
        VS["VS Code"]
        EsLint["ESLint Extension"]
        Prettier["Prettier Extension"]
        Debugger["Debugger for Node.js"]
        Intel["IntelliSense / TypeScript"]
    end

    subgraph Tools["Essential Tools"]
        Nodemon["nodemon — Auto-restart"]
        Jest["Jest — Testing"]
        Git["Git + .gitignore"]
        Dotenv["dotenv — Env variables"]
    end

    subgraph Project["First Project"]
        Init["npm init -y"]
        Deps["npm install express"]
        Scripts["Add start script"]
        Run["npm run dev"]
    end

    Base --> IDE
    Base --> Tools
    Tools --> Project

    style Base fill:#4f46e5,color:#fff
    style IDE fill:#7c3aed,color:#fff
    style Tools fill:#059669,color:#fff
    style Project fill:#d97706,color:#fff

sequenceDiagram
    participant Dev as Developer
    participant Terminal as Terminal
    participant Nvm as nvm
    participant Npm as npm
    participant VSCode as VS Code

    Dev->>Terminal: mkdir my-project && cd my-project
    Dev->>Terminal: nvm use 18
    Terminal->>Nvm: Switch to Node 18

    Dev->>Terminal: node --version
    Terminal-->>Dev: v18.17.0

    Dev->>Terminal: node -e "console.log('18' in nvm use 20)"
    Dev->>Terminal: echo "18" > .nvmrc

    Dev->>Terminal: npm init -y
    Terminal->>Npm: Create package.json

    Dev->>Terminal: npm install express
    Terminal->>Npm: Install express@4.18.2
    Npm-->>Terminal: ✅ node_modules/ + package-lock.json

    Dev->>Terminal: code .
    Terminal->>VSCode: Open in VS Code

// package.json — Essential fields
{
  "name": "my-project",
  "version": "1.0.0",
  "private": true,          // Prevent accidental publish
  "type": "module",          // Use ES Modules
  "engines": {
    "node": ">=18.0.0",     // Minimum Node version
    "npm": ">=9.0.0"
  },
  "scripts": {
    "start": "node src/server.js",
    "dev": "node --watch src/server.js",
    "test": "node --experimental-vm-modules node_modules/.bin/jest"
  }
}

// verify.js — Run to confirm your installation works
const fs = require('fs');
const path = require('path');
const os = require('os');
const crypto = require('crypto');

console.log('═══════════════════════════════════');
console.log('   Node.js Setup Verification');
console.log('═══════════════════════════════════\n');

// Version info
console.log(`✅ Node.js  : ${process.version}`);
console.log(`✅ npm       : ${require('child_process').execSync('npm --version').toString().trim()}`);
console.log(`✅ Platform  : ${os.platform()} (${os.arch()})`);
console.log(`✅ CWD       : ${process.cwd()}\n`);

// Test core modules
console.log('📦 Core Modules:');
fs.writeFileSync('test.txt', 'Hello Node.js!');
const content = fs.readFileSync('test.txt', 'utf-8');
console.log(`   fs: "${content}"`);
fs.unlinkSync('test.txt');

const hash = crypto.createHash('sha256').update('test').digest('hex');
console.log(`   crypto: SHA256('test') = ${hash}`);
console.log(`   path: ${path.join('a', 'b', 'c')}`);
console.log(`   os: ${os.cpus().length} CPUs, ${Math.round(os.freemem() / 1024 / 1024)}MB free\n`);

// Create a simple HTTP server (run briefly)
const http = require('http');
const server = http.createServer((req, res) => {
  res.end('OK');
});
server.listen(0, () => {
  const port = server.address().port;
  console.log(`✅ http: Server started on port ${port}`);
  server.close();
  console.log('✅ Setup verification complete! 🎉');
});

// .vscode/launch.json — Debugger configuration
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Server",
      "program": "${workspaceFolder}/src/server.js",
      "runtimeArgs": ["--watch"],
      "env": {
        "NODE_ENV": "development",
        "PORT": "3000"
      },
      "envFile": "${workspaceFolder}/.env",
      "skipFiles": ["<node_internals>/**"],
      "outFiles": ["${workspaceFolder}/dist/**/*.js"]
    },
    {
      "type": "node",
      "request": "attach",
      "name": "Attach to Process",
      "port": 9229,
      "restart": true
    }
  ]
}

// .vscode/extensions.json — Recommended extensions
{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "ms-vscode.vscode-typescript-next",
    "usernamehw.errorlens"
  ]
}

// .vscode/settings.json — Workspace settings
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "files.exclude": {
    "node_modules/": true,
    "dist/": true
  },
  "javascript.updateImportsOnFileMove.enabled": "always",
  "typescript.updateImportsOnFileMove.enabled": "always"
}

# Dockerfile — Multi-stage build
# Stage 1: Development
FROM node:20-alpine AS development

WORKDIR /app

# Install system dependencies
RUN apk add --no-cache curl git

# Copy package files
COPY package*.json ./
RUN npm ci

# Copy source code
COPY . .

EXPOSE 3000

CMD ["node", "--watch", "src/server.js"]

# Stage 2: Production build
FROM node:20-alpine AS production

WORKDIR /app

COPY package*.json ./
RUN npm ci --omit=dev && npm cache clean --force

COPY --from=development /app/dist ./dist

USER node

EXPOSE 3000

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD node -e "require('http').get('http://localhost:3000/health', r => {process.exit(r.statusCode === 200 ? 0 : 1)})"

CMD ["node", "dist/server.js"]

When you run npm install, npm:
1. Checks local cache: ~/.npm/_cacache/
2. If cached → extracts from cache (fast)
3. If not cached → fetches from registry
4. Saves to cache for future use
5. Extracts to node_modules/

npm cache path:
  macOS/Linux: ~/.npm/_cacache/
  Windows: %AppData%/npm-cache/

Clear cache if corrupted:
  npm cache clean --force

internal/modules/cjs/loader.js:818
  throw err;
  ^

Error: Cannot find module 'express'