Dart Version Management and Migration

Goal

Manages Dart language versioning, resolves breaking changes during SDK upgrades, and applies per-library version overrides to facilitate gradual migrations. Assumes a standard Dart or Flutter environment with access to pubspec.yaml and source files. Related Skills: dart-web-development, dart-static-analysis.

Decision Logic

When tasked with upgrading a Dart project or fixing version-related compilation errors, follow this evaluation path:

1. Identify Target SDK: Determine the target Dart SDK version.
2. Check Current Version: Read pubspec.yaml to find the current lower bound SDK constraint.
3. Evaluate Breaking Changes: Cross-reference the version jump with the breaking changes log.
   • If migrating to >= 3.0.0: Sound null safety is strictly enforced.
   • If migrating web libraries to >= 3.3.0: Legacy dart:html and dart:js are deprecated/removed.
4. Determine Migration Strategy:
   • Can the code be refactored immediately? -> Apply API migrations.
   • Is the refactor too large or blocked? -> Pin specific files using @dart = <version> to maintain older language semantics while upgrading the package.

Instructions

1. Verify Current Language Version Requirements Inspect the pubspec.yaml file to determine the default language version, which is dictated by the lower bound of the SDK constraint.

   environment:
     sdk: '>=2.18.0 <3.0.0' # Defaults to Dart 2.18
   

2. Consult Breaking Change Logs Before performing major dependency or SDK upgrades, review the breaking changes for the target version. STOP AND ASK THE USER: "I am about to upgrade the SDK constraint to <target_version>. This includes breaking changes such as <list_key_changes>. Should I proceed with the upgrade and begin refactoring?"

3. Apply Per-Library Language Version Selection (Gradual Migration) If a specific file cannot be immediately migrated to the new language version (e.g., pending null safety migration or complex refactoring), pin the file to an older version.

   • The @dart string must be in a // comment.
   • It must appear before any Dart code in the file.

   // @dart = 2.19
   import 'dart:math';
   
   // Legacy code that relies on 2.19 semantics
   void legacyFunction() {
     // ...
   }
   

4. Migrate Deprecated Web and JS Interop Libraries (Dart 3.3+) If the project targets Dart 3.3+ or compiles to Wasm, legacy web libraries (dart:html, dart:js, package:js) will cause compilation errors. Migrate these to package:web and dart:js_interop.

   // BEFORE (Legacy)
   import 'dart:html';
   import 'package:js/js.dart';
   
   @JS()
   external void legacyJsFunction();
   
   // AFTER (Modern)
   import 'package:web/web.dart' as web;
   import 'dart:js_interop';
   
   @JS()
   external void modernJsFunction();
   
   void updateDom() {
     final div = web.document.createElement('div') as web.HTMLDivElement;
     div.text = 'Migrated';
     web.document.body?.append(div);
   }
   

5. Validate-and-Fix Loop After updating the SDK constraint or modifying code, run static analysis to verify the migration.

   dart analyze
   

   Fixing common post-upgrade errors:

   • If unnecessary_non_null_assertion or invalid_null_aware_operator appears, remove the ! or ?. as type promotion has likely improved in the newer Dart version.
   • If dart:js_util or dart:html throws Wasm compilation errors, return to Step 4.

Constraints

• DO check current language version requirements in pubspec.yaml before making any syntax changes.
• DO use @dart = <version> to pin specific files to older versions during migration if a full refactor is not requested.
• DO consult breaking change logs before performing major dependency upgrades.
• NEVER use /// or /* */ for the @dart version override comment; it must be //.
• NEVER place the @dart comment after imports or code declarations.
• NEVER attempt to use dart:html, dart:js, or dart:js_util when compiling to WebAssembly (dart compile wasm).
• NEVER disable sound null safety in Dart 3.0+; the --no-sound-null-safety flag and unsound execution are completely removed.