Node.js Fix, Crash & Optimization Guide

Node.js is a JavaScript runtime built on V8 that lets you run JS outside the browser, and npm is its default package manager. This guide targets the errors developers hit during install, dependency management, and large builds.

Install / First Setup

• macOS/Linux (recommended): install nvm (Node Version Manager): curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash then nvm install --lts and nvm use --lts.
• Windows: use nvm-windows, or winget install OpenJS.NodeJS.LTS.
• Linux (system): NodeSource provides apt/yum repos; avoid old distro packages.

Verify with node --version and npm --version.

Common Issues & Fixes

EACCES: permission denied when installing global packages

Cause: npm tries to write to a system directory (e.g. /usr/lib/node_modules) without permission. Fix: Do NOT use sudo npm. Install Node via nvm so globals live in your home dir. Alternatively set a user prefix: npm config set prefix ~/.npm-global, add ~/.npm-global/bin to your PATH, then reinstall.

npm: command not found

Cause: Node.js is not installed or its bin directory is missing from PATH. Fix: Reinstall Node (prefer nvm), then confirm which node and which npm point inside your home or Node install dir.

Version mismatch / "wrong node version" between terminals

Cause: Multiple Node installs; the default version differs per shell or per project. Fix: With nvm, nvm use 20 (or your version) and nvm alias default 20. Use an .nvmrc file in the project so nvm use picks the right one automatically.

npm ERR! code EINTEGRITY

Cause: Corrupted or stale npm cache, or a registry/proxy returning mismatched tarball hashes. Fix: npm cache clean --force, then npm install again. If behind a proxy mirror, confirm the mirror is in sync.

Cannot find module '<x>' at runtime

Cause: Dependencies were never installed, or node_modules is missing/stale after a branch switch. Fix: Run npm install, confirm package.json/package-lock.json exist, and check you are in the project root. For TypeScript/ESM path issues, see the TypeScript guide.

Performance & Optimization

• Low-End (4–8 GB): Keep dependencies minimal; remove unused packages with npm prune. Use npm ci in CI for reproducible, faster installs from the lockfile.
• Mid (16 GB): For large builds that crash with "heap out of memory," raise the limit: export NODE_OPTIONS=--max-old-space-size=4096 before running npm run build / vite build / webpack.
• Workstation (32 GB+): Parallelize with npm run build -- --max-workers=N, keep node_modules on a fast SSD, and consider pnpm for hard-linked, disk-efficient installs on big monorepos.

General: prefer npm ci over npm install in pipelines, and commit package-lock.json.

Version & Compatibility Notes

• Node.js uses even-numbered LTS lines: 18, 20, 22 are recent LTS releases. Odd majors (e.g. 21) are short-lived "current" lines, not LTS.
• Node 16 reached end-of-life; do not target it for new projects.
• npm ships with Node; major npm versions track Node releases. For exact supported versions and EOL dates, consult official release notes.

FAQ

Q: Should I use sudo npm install -g? A: No. Use nvm so global packages install into your home directory, or set a user prefix. sudo with npm risks permission and security problems.

Q: What's the difference between npm install and npm ci? A: npm ci deletes node_modules and installs exactly from package-lock.json, making it faster and reproducible — ideal for CI. npm install may update the lockfile.

Q: How do I switch Node versions per project? A: With nvm, add an .nvmrc containing the version (e.g. 20) and run nvm use. nvm reads it automatically on shell start if configured.

Q: My build dies with "JavaScript heap out of memory." How do I fix it? A: Raise the old-space limit: NODE_OPTIONS=--max-old-space-size=4096 npm run build. Size it to your RAM but leave headroom for the OS.

Q: npm is slow. Should I switch package managers? A: For large monorepos, pnpm or yarn can be much faster and use less disk via content-addressable storage. For small projects npm is fine.

Q: How do I check which Node version a project needs? A: Look at the engines field in package.json, or the .nvmrc/CI config. Match it with nvm install <version>.

Related Guides

• Python Fix & Optimization Guide
• TypeScript Fix & Optimization Guide
• Rust Fix & Optimization Guide
• Dev RAM Calculator

Accuracy Note

Commands and paths reflect common, real-world setups as of 2026-08. Always verify against your installed version and OS. When in doubt, consult the official Node.js documentation.