Migrating a Flutter App to Null Safety: Lessons Learned

If you are still on a pre-null-safety Flutter codebase, the migration is overdue but not scary. Most of it is mechanical. The interesting part is the pattern decisions you cannot automate, and those are worth thinking through before you run dart migrate.

Run the migration tool first

dart migrate gives you an interactive web UI showing what will change. It is conservative — it adds ? everywhere it cannot prove non-null. The result compiles but has way too many nullable types. Use it to understand the surface area, then refine manually.

Decide on Late vs ?

Variables that are non-null but assigned after construction (controllers, late state) should be late, not ?. Using ? everywhere means every read site has to handle null even when you know it cannot be.

Use ? for genuinely optional fields (an age that might be missing). Use late for fields that will be set before any read but cannot be set in the constructor.

Handle the API boundary

JSON from APIs lies. Even when the spec says a field is required, real responses sometimes omit it. Wrap fromJson() in defensive parsing — provide defaults for missing fields, throw a clear error when something truly required is missing. Do not let a bad response crash your app at a random later read.

Tests after migration

Once the migration compiles, run the full test suite. Most failures will be real null mismatches that were latent before — places where the old code accepted null and silently misbehaved. Each failure is the migration paying for itself.