Migrate an existing Flutter app to Flutter 2.0

After I read that many people have issues with their projects after upgrading to Flutter 2.0, I decided to write this quick tutorial. So, as you have already guessed, we’ll be covering how to migrate an existing Flutter app to Flutter 2.0 and to sound null-safety.

First of all, to upgrade your Flutter SDK you need to open the terminal and run the following command.

flutter upgrade

This will upgrade your Flutter SDK in the currently active channel. If you need to change your channel just run the following command and replace <channel> with the name of the channel you want to switch to.

flutter channel <channel>

After the upgrade is completed, you’ll be able to run your app with Flutter 2.0 without any issues.
Yes, it is as easy as this!

Now you should be seeing something like this in your terminal. Please ignore the error above ;)

What about null safety? And what does this ‘unsound’ mean?

First of all, we need to quickly go over the null safety topic. So what is null safety now? Null safety describes a technique to declare that variables cannot be null until you explicitly say they can.
Null-safety in Dart is based on the following three principles.

Non-nullable by default.
Unless you explicitly tell Dart that a variable can be null, it’s considered non-nullable. This default was chosen after research found that non-null was by far the most common choice in APIs.

Incrementally adoptable.
You choose what to migrate to null safety, and when. You can migrate incrementally, mixing null-safe and non-null-safe code in the same project. We provide tools to help you with the migration.

Fully sound.
Dart’s null safety is sound, which enables compiler optimizations. If the type system determines that something isn’t null, then that thing can never be null. Once you migrate your whole project and its dependencies to null safety, you reap the full benefits of soundness — — not only fewer bugs, but smaller binaries and faster execution.

For Reference and more detailed information please visit: https://dart.dev/null-safety

So what does ‘Running your app with unsound null safety’ mean?

This basically means that our app is running a version of the Flutter framework that is already ported to null-safety, but the app itself is not null safe yet.

So is this any kind of a problem?

No, it isn’t. You can code, test, run and compile your app the same way as before.

If you now want to migrate your app to null safety, there a few things we need to keep an eye on.

The first question might be ‘Is our app ready to migrate?’ but the more important question should be ‘Are our packages ready to migrate?’.
To find out the Dart team provides an easy command to check whether our app and the dependencies are ready to be migrated or not.

flutter pub outdated --mode=null-safety

After running this command you should be seeing something like this in your terminal.

Terminal output after running ‘flutter pub outdated — mode=null-safety’

As you can see these dependencies are quite outdated… I’m sorry for that.

The ‘x’ indicates versions in the table without null safety support.
The checkmark indicates versions opting into null safety.

If all you’re dependencies are opting into null safety you can update these dependencies in your pubspec.yaml. You can update your dependencies manually or by running the two following commands in your terminal.

dart pub upgrade --null-safety
dart pub get

Note: running dart pub upgrade will change your pubspec.yaml file as it needs to change the versions of your dependencies.

After updating all dependencies we are ready to migrate to null safety. Therefore you can run the following command in the terminal.

dart migrate

NOTE: You should only try to migrate to null safety if ALL your dependencies are compatible with null safety!

In further progress, you can preview all change suggestions of the tool before actually migrating, by opening the localhost address shown in the terminal in your browser.

http://127.0.0.1:60278/Users/you/project/mypkg.console-simple?authToken=Xfz0jvpyeMI%3D

If you have opened the address above you’ll be seeing a window like this.

https://dart.dev/null-safety/migration-tool.png

On the left side of the tool, you can see a tree of your project files. You can select which files you want to migrate or not. In the middle, you (obviously) see the code and the suggested changes. On the right side, we can see details of the edits.
If you previewed all changes and accept them you can migrate by hitting the button ‘Apply Migration’.

Now the tool changes your files and you will see that it is perfect to do all the ‘mechanical’ work for you, but sometimes it will get things wrong. So make sure that you checked your code for possible errors or misconceptions.

You also have the opportunity to change inside the migration tool whether you want the change a specific line of code or not.

For more detailed information regarding migration to null safety and the migration tool, I’ll highly recommend heading on over to https://dart.dev/null-safety/migration-guide

The Dart team has done an amazing job with these extremely well-done docs. They are explaining each step in more detail than I would be able to do anyways.
But if you have any questions feel free to hit me up in the comments!

Stay safe and happy coding!