Dependency Conflict Triage

How It Works

Dependency conflicts are common, especially with peer dependencies and fast-moving ecosystems.

This recipe standardizes triage and resolution options.

Triggers

• Install fails with dependency resolution errors
• Peer dependency conflicts block onboarding or CI
• Teams "fix" by deleting lockfiles or force-installing

Steps

1. Identify the conflict graph: who requires what version and why.
2. Prefer deterministic install paths:

• use lockfiles,
• avoid deleting lockfiles as a "fix."

1. Choose a strategy:

• upgrade the blocker package,
• pin and align versions,
• replace/remove incompatible dependency,
• isolate via workspace/package boundaries.

1. Validate in CI with clean installs and cache disabled once.
2. Document the decision and add a "dependency policy" note.

Expected Outcome

• Conflicts are resolved with understanding, not superstition.
• CI and onboarding become more reliable.

Example Inputs

• "npm ERESOLVE peer dependency conflict."
• "Composer dependency conflict between A and B."
• "Two packages require different major versions of C."

Tips

• "--force" is a last resort: it can create broken, untestable states.