Dart 2 has a few key differences from earlier versions of Dart. This page briefly covers those differences and gives general advice on migrating your code to Dart 2.
For information on why Dart 2 has changed, see the Dart 2 announcement.
The Dart language, libraries, build system, and web development tools have changed.
Language and libraries
- Dart’s type system is now sound.
- Dart no longer has checked mode.
- Assert statements are still supported, but you enable them differently.
- The Dart language and core libraries have changed, partly as a result of the type system changes.
- Pub no longer supports transformers. Instead, use the new build system.
- Tools related to web development have changed.
Migrating your code
First, see the migration guide for your platform:
If you publish packages, then also see the package migration instructions below.
Here’s an overview of the process of migrating to Dart 2, from either Dart 1.x or an earlier version of Dart 2.
- Get an up-to-date version of the Flutter or Dart SDK.
- Upgrade the packages your app depends on.
- Run the dart2_fix tool.
- Run the analyzer to find compile-time errors.
- Fix issues in your code and run the analyzer again, repeating until your code passes static analysis.
Run tests to find runtime errors.
- Run all automated tests for your software.
- Do manual testing, and look for console errors. Consider adding automated tests to catch issues that you find.
- Fix issues until your code works.
Each time the SDK has a significant release, repeat the process.
As a package owner, you need to do the following:
- Follow the migration tips for the platforms that your package supports (see above).
- Make sure your package’s users know how to report issues.
- Respond quickly to issue reports.
- If code changes aren’t backward compatible, update the lower SDK constraint.
Changes and backward compatibility
If you have to change your package’s code, try to make it work in 1.x, as well as Dart 2. For example, you might be able to add type annotations or (if an API has been removed) to use an alternative 1.x API.
If a backward-compatible change isn’t possible, update the lower SDK constraint.
Test your changes to make sure that your package works as expected.
Upper constraints on the SDK version
Don’t update an already-published package
solely to indicate that it can be used with Dart 2 pre-releases.
As long as a package has either no SDK constraints
or an upper constraint of
pub get and similar pub commands in any Dart 2 pre-release
can download the package.
(The package won’t be usable with Dart 2 stable releases,
but you can fix that later.)
When you update an existing package or publish a new one,
specify an upper constraint of
<2.0.0 for the SDK version. Examples:
# Works in 1.20.1+; might work in 2.0.0-dev: sdk: '>=1.20.1 <2.0.0' # Backward incompatible change requires at least 2.0.0-dev.1.2: sdk: '>=2.0.0-dev.1.2 <2.0.0'
Eventually, you’ll need to publish new versions of your packages to
declare Dart 2 compatibility, most likely using a
<3.0.0 SDK constraint.
Because incompatible changes might occur in any Dart 2 pre-release,
don’t declare Dart 2 compatibility until we announce that it’s safe to do so.