Dart Version Management and Migration

Goal

pubspec.yaml

dart-web-development

dart-static-analysis

Decision Logic

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.
   yaml

   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

   // @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

   .
   dart

   // 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.
   bash

   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.