Bun Peer Dependency Resolution Issues: Technical Reference

Root Cause Analysis

Core Problem: Bun's dependency resolver prioritizes latest versions over compatibility, causing peer dependency conflicts with ESLint and TypeScript tooling.

Specific Behavior Difference:

• npm: Conservative resolution - selects oldest compatible version (e.g., ESLint 8.57.0)
• Bun: Aggressive resolution - selects newest compatible version (e.g., ESLint 9.16.0)

Impact Severity: High - breaks linting and TypeScript configurations in production environments

Failure Modes and Symptoms

Critical Errors

1. EREQUIRE_ESM Error

   • Cause: ESLint 9's ESM-first approach conflicts with CommonJS-expecting packages
   • Trigger: Running bunx eslint src/
   • Impact: Complete linting failure

2. Silent TypeScript Rule Failures

   • Cause: Version mismatch between ESLint and @typescript-eslint packages
   • Symptom: Rules ignored without error messages
   • Detection: Rules not enforced despite configuration

3. Warning Spam

   • Output: Hundreds of "incorrect peer dependency" warnings
   • Impact: Obscures actual issues, creates noise in CI/CD

Platform-Specific Issues

• Windows: ENAMETOOLONG errors due to longer node_modules paths
• Node 18.2.0: Specific version breaks Bun's ESLint integration
• M1 Macs: Native dependency architecture conflicts with @esbuild packages

Proven Solutions

1. Version Forcing (Primary Fix)

Implementation Time: 30 seconds
Success Rate: 95% of cases

{
  "resolutions": {
    "eslint": "8.57.0",
    "@typescript-eslint/eslint-plugin": "7.18.0",
    "@typescript-eslint/parser": "7.18.0"
  }
}

Recovery Process:

rm -rf node_modules bun.lockb package-lock.json
bun install

2. Exact Version Pinning (Prevention)

When: Start of new projects
Maintenance Overhead: Minimal - prevents future issues

{
  "devDependencies": {
    "eslint": "8.57.0",
    "@typescript-eslint/eslint-plugin": "7.18.0"
  }
}

3. Hybrid Approach (High Reliability)

Use Case: Complex projects with 100+ dependencies
Performance Trade-off: Slower installs, faster everything else

npm install      # Installation with npm
bun run dev      # Execution with Bun
bun run build
bun test

4. Configuration Override (Last Resort)

bunfig.toml:

[install]
exact = true
peer = false

Warning: Unstable across Bun versions (broken in v1.2.x updates)

Tested Version Matrix

Framework	ESLint	TypeScript	@typescript-eslint/*	Status (Bun 1.2.21)
React 18	8.57.0	5.5.4	7.18.0	✅ Stable
Next.js 14	8.57.0	5.5.4	7.18.0	⚠️ Watch eslint-config-next
Vite	8.57.0	5.5.4	7.18.0	✅ No issues
Turborepo	8.57.0	5.5.4	7.18.0	⚠️ Workspace deps buggy

Framework-Specific Gotchas

Next.js 14

• Breaking Point: eslint-config-next incompatible with ESLint 9
• Required Resolution: Force ESLint 8.57.0
• Config: "eslint-config-next": "14.2.5"

Vite Projects

• Issue: @vitejs/plugin-react peer dependency conflicts
• Solution: Same version pinning approach

Diagnostic Commands

Immediate Issue Detection

bun pm ls | grep eslint          # Check installed ESLint version
bunx eslint --version            # Verify executable version
bunx eslint src/                 # Test functionality

Pre-Installation Validation

#!/bin/bash
rm -rf node_modules bun.lockb
bun install 2>&1 | tee /tmp/install.log
if grep -q "incorrect peer dependency" /tmp/install.log; then
    echo "💩 Dependency conflicts found"
    exit 1
fi

Resource Requirements

Time Investment

• Initial Setup: 30 seconds (version forcing)
• Project Start: 5 minutes (proper pinning)
• Debugging Without Guide: 2-3 hours average
• Recovery Time: 30 seconds with known solution

Expertise Requirements

• Minimum: Basic package.json understanding
• Preferred: npm/yarn resolution mechanism knowledge
• Team Training: Document working versions, establish update protocols

Decision Criteria

Stay with Bun When:

• Simple projects (<50 dependencies)
• Can implement version forcing in 5 minutes
• Speed boost outweighs occasional debugging

Switch to npm When:

• Complex dependency chains (100+ packages)
• Production applications requiring stability
• Team environment with multiple developers
• Frequent breaking changes consuming development time

Critical Warnings

1. Never ignore major version peer dependency mismatches - leads to silent failures
2. Bun 1.2.x broke bunfig.toml configurations - test thoroughly before relying on config overrides
3. ESLint 9 + TypeScript ESLint compatibility still unstable as of August 2025
4. Windows PATH limits can cause ENAMETOOLONG errors with Bun's node_modules structure

Emergency Fallback

{
  "scripts": {
    "install:bun": "bun install",
    "install:npm": "npm install",
    "deps:check": "./check-deps.sh"
  }
}

When Bun updates break existing projects, immediate fallback to npm install prevents project downtime.

Status Tracking

• GitHub Issue: #15711 (December 2024)
• Resolution Timeline: Requires rewriting Bun's dependency resolver
• Workaround Stability: High for version forcing, unstable for config overrides