dart-resolve-package-conflicts
Workflow for fixing package version conflicts. Use this when `pub get` fails due to incompatible package versions.
SKILL.mdskills/dart/dart-resolve-package-conflicts/SKILL.md
GitHubContents
- Core Concepts
- Version Constraints
- Workflow: Auditing Dependencies
- Workflow: Upgrading Dependencies
- Workflow: Resolving Version Conflicts
- Examples
Core Concepts
Dart enforces a strict single-version rule: a project and all its transitive dependencies must resolve to a single, shared version of any given package.
Understand dart pub outdated columns:
- Current: Version in
pubspec.lock. - Upgradable: Latest version allowed by
pubspec.yamlconstraints. - Resolvable: Latest version factoring in all other dependencies.
- Latest: Latest published version (excluding prereleases).
Version Constraints
- Use Caret Syntax: Always use
^1.2.3for dependencies. - Tighten Dev Dependencies: Set lower bound to exact version currently used.
- Enforce Lockfiles in CI: Use
dart pub get --enforce-lockfile.
Workflow: Auditing Dependencies
- Run
dart pub outdated. - Review Upgradable column.
- Review Resolvable column.
- Identify retracted or discontinued packages.
Workflow: Upgrading Dependencies
- If updating to "Upgradable" versions:
- Run
dart pub upgrade. - Run
dart pub upgrade --tighten.
- Run
- If updating to "Resolvable" versions (Major updates):
- Manually edit
pubspec.yamlto bump the version constraint. - Run
dart pub upgrade.
- Manually edit
- Feedback Loop:
- Run
dart analyze-> review errors -> fix. - Run
dart test-> review failures -> fix.
- Run
Workflow: Resolving Version Conflicts
NEVER delete the entire pubspec.lock file.
- Open
pubspec.lock. - Locate the specific YAML block for the conflicting package.
- Delete ONLY that package's entry from the lockfile.
- Run
dart pub get. - Feedback Loop:
- Run
dart pub deps-> verify the dependency graph. - If resolution fails, update its constraint in
pubspec.yamland retry.
- Run
Example: Tightening Constraints
dart pub upgrade --tighten http
# Before: http: ^0.13.0
# After: http: ^0.13.5
Example: Surgical Lockfile Removal
Delete only the conflicting package block from pubspec.lock, leave others untouched, then run dart pub get.