Enabling Flutter Null Safety in an Existing Project

Desired outcome

Enable sound null safety for a Flutter project so that the Dart analyzer treats all types as non‑nullable by default, reducing runtime null‑reference errors and unlocking IDE assistance.

Prerequisites

• Flutter SDK version >=2.0.0 (null safety support landed in Flutter 2).
• Dart SDK version >=2.12.0 (included with Flutter 2).
• A version‑controlled repository (e.g., Git) with a clean working directory or a recent commit you can return to.
• Access to run flutter and dart commands from the project root.

Procedure

1. Create a backup branch or tag. From the project root run:

   git checkout -b null-safety-migration

   This isolates the migration work.
2. Run the automated migration tool. Execute:

   flutter pub migrate

   The tool updates your source files and generates a diff. Review the changes carefully; it will also attempt to update dependencies to null‑safe versions where possible.
3. Resolve remaining opt‑outs. After the migration finishes, you may see files with // ignore: avoid_as or similar comments, or // @dart=2.9 opt‑out markers. Remove these markers only after you have verified that the code no longer needs them, or keep them temporarily if a dependency still requires the old syntax.
4. Update SDK constraints. In pubspec.yaml set the environment SDK constraint to a null‑safe range, for example:

   environment:
     sdk: ">=2.12.0 <3.0.0"

   If you are using a newer Flutter stable channel, you can extend the upper bound accordingly (e.g., <=3.0.0 or omit it).
5. Configure the analyzer. Ensure analysis_options.yaml contains:

   analyzer:
     enable-experiment:
       - non-nullable
   language:
     strict-cases: true
   linter:
     rules:
       - avoid_null_checks_in_equality
       - unnecessary_null_comparison

   If you rely on the default SDK constraint, the enable-experiment line can be omitted, but keeping it makes the intent explicit.
6. Run a full analysis. From the project root:

   flutter analyze

   or dart analyze. The output should show zero null‑safety warnings or errors.
7. Execute the test suite. Run unit, widget, and integration tests:

   flutter test

   If any test fails because of a null‑safety issue, fix the offending code before proceeding.
8. Verify dependency compatibility. Check that all direct and transitive dependencies are null‑safe:

   flutter pub outdated --mode=null-safety

   Any package reported as “pre‑null‑safety” must be upgraded, forked, or patched.

Expected checks

• flutter analyze returns an empty warning list (or only non‑null‑safety related hints).
• The flutter pub outdated --mode=null-safety command shows no packages with a red “pre‑null‑safety” flag.
• All tests pass (flutter test exit code 0).
• The application builds successfully for at least one target (e.g., flutter build apk --debug or flutter run).

Recovery options

If a critical issue appears after migration:

1. Revert to the backup branch:

   git checkout main

   or the branch you created before migration.
2. Alternatively, reset the migration commit:

   git reset --hard HEAD~1

   (adjust the number of commits as needed).
3. Re‑apply any local changes that were not committed, then re‑evaluate the migration steps or seek updated versions of problematic dependencies.