npm ERESOLVE Dependency Conflicts: AI-Optimized Technical Reference

Critical Failure Scenarios

High-Severity Breaks

• UI breaks at 1000+ spans: Makes debugging large distributed transactions impossible
• React 18.3 peer conflicts: Sudden incompatibility with previously working chart libraries
• TypeScript 5.x resolution changes: ESLint plugins, testing libraries, build tools stop working
• ESM vs CommonJS disasters: ERR_REQUIRE_ESM errors from undocumented ESM-only packages

Deployment Blockers

• 2am hotfix deployment failures: Business-critical patches blocked by dependency conflicts
• CI passes, production fails: Different Node versions resolve dependencies differently
• "Works on my machine": Inconsistent node_modules across environments

Root Cause Analysis

npm Algorithm Limitations

• Peer dependency flattening failures: npm cannot reconcile conflicting peer dependency versions
• Transitive dependency hell: Conflicts from packages buried 3+ levels deep
• Legacy package maintenance: Libraries still declaring React 17 peer deps in 2025 (3 years after React 18 release)

Version Range Problems

• Semver range conflicts: "^4.0.0" vs "^3.10.1" for same package (lodash v3/v4 incompatibility)
• Peer dependency strictness: npm v7+ stricter than v6 resolver
• Breaking "minor" updates: TypeScript 5.x changed module resolution, breaking ecosystem

Immediate Solutions (Ranked by Success Rate)

1. Nuclear Reset (80% success rate, 5-120 minutes)

rm -rf node_modules package-lock.json
npm cache clean --force
npm install --legacy-peer-deps

When it fails: Deep transitive conflicts, actual incompatibilities

2. npm Overrides (90% success rate, 15-60 minutes)

{
  "overrides": {
    "react": "^18.2.0",
    "some-problematic-package": {
      "react": "^18.2.0"
    }
  }
}

Critical advantage: Surgical control over specific conflicts
Failure mode: When packages are fundamentally incompatible

3. Version Pinning (95% prevention rate)

{
  "dependencies": {
    "react": "18.2.0",    // exact, not "^18.2.0"
    "typescript": "5.1.6"
  }
}

Resource Requirements

Time Investment

• Quick fixes: 5 minutes (nuclear reset) to 2 hours (npm cache corruption)
• Override implementation: 15 minutes identification + 1 hour fixing cascading breaks
• Package updates: 30 minutes → dependency rabbit hole (2-8 hours)
• Fork-and-fix: Half day initial + ongoing maintenance burden
• Framework upgrades: 1 week full-time (React 18→19, Next.js major versions)

Expertise Costs

• Junior developers: 4+ hours debugging what senior resolves in 30 minutes
• Team coordination: Weekly 30-minute maintenance vs 2-hour emergency debugging sessions
• Business impact: Feature delays while explaining "button library has opinions about React versions"

Production-Ready Configurations

Docker Builds

FROM node:18-alpine
RUN npm install -g npm@9.8.1
ENV NPM_CONFIG_LEGACY_PEER_DEPS=true
COPY package*.json ./
RUN npm ci --only=production

CI/CD Pipeline Protection

- name: Install with legacy peer deps
  run: npm ci --legacy-peer-deps
- name: Check dependencies
  run: npm ci --dry-run

Decision Criteria

When to Use --legacy-peer-deps

• Immediate deployment pressure: 3pm deploy, 2-hour deadline
• Migration scenarios: npm v6→v7+ upgrades
• Unmaintained libraries: Packages with ancient peer deps

When to Use Overrides

• Surgical precision needed: Specific package conflicts
• Long-term maintainability: Better than global legacy flag
• Team environments: Explicit conflict resolution documentation

When to Fork Packages

• Abandoned maintainers: No updates for 6+ months
• Critical business dependency: Package essential, no alternatives
• Simple peer dep fixes: One-line package.json changes

Critical Warnings

What Documentation Doesn't Tell You

• Lock file commitment mandatory: Ignore = "works on my machine" hell
• Semver is unreliable: "Minor" updates break production regularly
• Different Node versions = different resolutions: Use .nvmrc files
• npm cache corruption: Causes 2-hour debugging sessions

Breaking Points

• 1000+ dependency packages: Resolution becomes computationally expensive
• Mixed ESM/CommonJS: Incompatible module systems in same project
• React 16→18 ecosystem lag: 50% of UI libraries still incompatible
• TypeScript major versions: Break entire toolchain (ESLint, testing, build)

Prevention Strategies

Essential Practices

{
  "engines": {
    "node": "18.17.0",
    "npm": "9.8.1"
  }
}

Pre-Installation Checks

npm info package-name peerDependencies
npx bundlephobia package-name  # Prevent 2MB date library disasters

Automated Monitoring

• Renovate bot configuration: Pin versions, disable major updates
• Security auditing: npm audit --audit-level high
• Dependency staleness: npm-check-updates weekly reviews

Alternative Package Managers

Migration Decision Matrix

• Yarn: Better peer dependency resolution than npm v7+
• pnpm: Stricter, faster, disk-efficient
• Bun: Ultra-fast, new ecosystem

Migration Risk Assessment

• Low risk: Delete package-lock.json, test with new manager
• Medium risk: Different resolution algorithms may surface hidden conflicts
• High risk: Team tool standardization, CI/CD pipeline changes

Troubleshooting Decision Tree

1. Immediate conflict: Try nuclear reset (5 minutes)
2. Reset fails: Implement overrides (30 minutes)
3. Override cascade failures: Pin problematic package versions
4. Fundamental incompatibility: Find alternative package or fork
5. No alternatives: Consider different package manager

Success Metrics

• Deployment velocity: From 4-hour conflict debugging to 15-minute override fixes
• CI reliability: 95% build success rate vs 60% with unmanaged dependencies
• Developer productivity: 30-minute weekly maintenance vs 3am emergency debugging
• Technical debt: Controlled override documentation vs scattered --force usage