npm Package Manager - Technical Reference

Configuration and Installation

Critical Installation Requirements

• NEVER use sudo with npm installations - breaks permissions system-wide
• Install via nvm to avoid permission conflicts
• Use npm ci in production environments (never npm install)
• npm 11.5.2 (latest as of July 30, 2025) provides 30% faster installations than npm 10

Production-Ready Settings

# Production installation
npm ci --only=production

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

# Fix permission issues (one-time setup)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

Resource Requirements

Time Investment

• Initial permission setup with nvm: 5 minutes (saves hours of debugging)
• Average install time npm 11: 3.5 minutes (was 5 minutes in npm 10)
• node_modules deletion and reinstall: 90% problem resolution rate

Disk Space Impact

• Single package installation: Typically downloads 247 dependencies
• Average node_modules size: 500MB for basic projects
• Multiple lodash versions common (15+ different versions per project)

Expertise Requirements

• Understanding symlinks essential for pnpm migration
• Stack Overflow dependency for ERESOLVE errors
• Dependency conflict resolution requires manual package version management

Package Manager Comparison Matrix

Criteria	npm 11	Yarn Classic	pnpm	Bun
Stability	Works everywhere	Works most places	Requires symlink understanding	Beta software - expect bugs
Performance	Baseline (slowest)	2x faster	3-4x faster	10x faster when stable
Disk Efficiency	Worst (full duplication)	Same as npm	Best (symlink deduplication)	Efficient but unproven
Enterprise Ready	Production safe	Facebook-tested	Good for monorepos	Too new for production
Learning Curve	Zero (default)	Minimal	Moderate (different workflow)	High (different everything)
Debug Support	Extensive Stack Overflow	Good community	Symlink troubleshooting required	Limited community support

Critical Failure Modes

High-Impact Failures

1. Permission Errors (Mac/Linux)

   • Cause: Global npm installation conflicts with system permissions
   • Solution: nvm installation (permanent fix)
   • Impact: Blocks all global package installations

2. ERESOLVE Dependency Conflicts

   • Cause: Incompatible package version requirements
   • Resolution order: Delete node_modules → npm install → --legacy-peer-deps → manual version pinning
   • Success rate: 60% with suggested fixes, 40% require Stack Overflow

3. package-lock.json Corruption

   • Trigger: Manual editing or merge conflicts
   • Solution: Delete lock file, regenerate with npm install
   • Prevention: Never manually edit lock files

Security Theater Issues

• npm audit false positives: 90% of "critical" vulnerabilities are in dev dependencies or unreachable transitive dependencies
• audit --force danger: Updates dependencies to breaking changes while claiming security fixes
• Package verification: New signature checking breaks builds when maintainers forget to sign

Implementation Reality vs Documentation

Default Settings That Fail in Production

• npm install modifies lock files unpredictably
• Global installations without nvm cause permission cascades
• npm audit suggestions break more than they fix

Actual vs Documented Behavior

• npm 11 "30% faster" = still slowest option available
• "Improved error messages" = longer but not more helpful
• Security updates often introduce breaking changes

Community Wisdom

• Delete node_modules fixes 90% of npm problems
• Remaining 10% require project restart
• pnpm provides superior monorepo support
• Bun performance gains real but stability questionable

Operational Workarounds

Common Problem Resolution

# Standard npm troubleshooting sequence
rm -rf node_modules package-lock.json
npm install

# If that fails
npm install --legacy-peer-deps

# For production
npm ci  # Never modifies lock file

Package Management Best Practices

• Use npm pack to test packages before publishing
• Start with version 0.0.1 (avoid 1.0.0 first publish)
• Check Bundle Phobia before adding dependencies
• Avoid packages with declining npm trends

Migration Considerations

Worth the Switch: npm → pnpm

• Benefits: Real performance gains, disk space efficiency, proper monorepo support
• Costs: Team retraining, symlink understanding required
• Timeline: 1-2 weeks for team adoption

Too Risky: npm → Bun

• Benefits: 10x performance improvement
• Costs: Beta software instability, limited community support
• Recommendation: Side projects only

Safe Alternative: npm → Yarn

• Benefits: Stability with performance improvement
• Costs: Different lock file format, minimal learning curve
• Timeline: 1-2 days migration

Essential Tools and Resources

Problem Resolution

• Stack Overflow npm tag: Primary troubleshooting resource
• npm CLI GitHub Issues: 1,200+ open issues confirm bugs
• npm-check-updates: Dependency update management

Security and Quality

• Socket.dev: Actual malicious package detection (npm audit replacement)
• Snyk: Meaningful vulnerability assessment
• Bundle Phobia: Dependency size impact analysis

Alternative Registries

• Verdaccio: Private registry that works
• GitHub Packages: Free for private repos

Decision Criteria

Stay with npm if:

• Team lacks bandwidth for migration
• Enterprise environment requires maximum stability
• Switching costs exceed performance benefits

Migrate to pnpm if:

• Monorepo architecture
• Disk space constraints
• Performance critical (3-4x improvement)
• Team can handle symlink debugging

Consider Bun if:

• Side projects or experimental work
• Performance absolutely critical
• Willing to debug beta software issues

Breaking Points and Thresholds

• node_modules approaching 1GB: Consider dependency audit
• Install times exceeding 10 minutes: Evaluate alternatives
• More than 5 ERESOLVE conflicts weekly: Team process issue
• npm audit showing 50+ vulnerabilities: Ignore or switch to Snyk