Adopting Dart Sound Null Safety: A Practical Migration Walkthrough

The Problem: Null‑Related Crashes in Dart

In pre‑null‑safety Dart, a variable could hold null unless you explicitly checked it. Forgetting a check led to runtime errors that felt like NullPointerException in other languages, often surfacing only after deployment and hurting user experience.

Thesis: Sound Null Safety Shifts Errors to Compile Time

Dart’s sound null safety makes every type non‑nullable by default. You must annotate a type with ? when it can legitimately be null. The analyzer then flags any possible dereference of a potentially null value before the code runs, turning many runtime crashes into static errors.

Worked Example: Making a JSON Parser Null‑Safe

Consider a simple function that extracts a user’s email from a JSON map:

String getEmail(Map json) {
  return json['user']['email'] as String;
}

This version assumes the nested keys exist and are strings. If any part is missing or null, the cast throws at runtime.

First, annotate the parameters and return type to reflect what can be null:

String? getEmail(Map? json) {
  if (json == null) return null;
  final user = json['user'] as Map?;
  if (user == null) return null;
  return user['email'] as String?;
}

Now the analyzer knows json, user, and the final result may be null. Any caller that forgets to check the return value gets a compile‑time warning.

If you are certain the email will always be present in a trusted data source, you can use late or a default instead of propagating nulls:

String getEmail(Map json) {
  final user = json['user'] as Map;
  return user['email'] as String ?? '[contact removed]';
}

This version eliminates nullable returns while still guarding against missing keys with a fallback.

Trade‑offs and Gotchas

• Verbosity: Adding ? and null checks can make code longer, especially during migration.
• Misuse of late and !: Using late without proper initialization or applying the null‑assertion operator (!) re‑introduces runtime null errors, weakening the guarantee.
• Dependency friction: Packages that have not adopted null safety may require version pins or temporary workarounds.

Actionable Steps to Migrate and Verify

1. Create a fresh null‑safe project (run in your shell, no special permissions needed):

   dart create --null-safety my_app
   cd my_app

   This generates a pubspec.yaml with environment: sdk: '>=2.12.0 <3.0.0''.
2. Run the analyzer to see the baseline:

   dart analyze

   Expect zero null‑safety warnings if the template is sound.
3. Migrate existing code using the migration tool:

   dart migrate --apply-changes

   The tool edits files in place; review the diff before committing.
4. Introduce a deliberate error to confirm the analyzer works: remove a required ? from a variable, run dart analyze, and observe the new warning. Fix it and verify the warning disappears.
5. Exercise the app to ensure no null‑related exceptions appear at runtime:

   dart run

   Test code paths that previously threw null errors; they should now be handled by the null‑safe logic or produce a compile‑time error instead.
6. Check dependencies: run dart pub outdated --mode=null-safety to see which packages need updating.