Contents

Breaking changes and deprecations

This page lists all language and library breaking changes and deprecations in Dart, organized by release and area, to help Dart users understand and manage their impact. Complete release notes are available in the Dart SDK changelog. The breaking change policy document describes the policy and process around breaking changes and deprecations in Dart.

This page includes the following types of breaking changes:

  • Unversioned: The Dart SDK does not maintain backward compatibility, and code may break as soon as you upgrade your sdk version if it relies on the previous behavior.

    These are the majority of changes and are not specially marked in this list.

  • Language versioned: The Dart SDK maintains backward compatibility for existing code, and the behavior change only takes effect (potentially breaking code that relies on the previous behavior) when you upgrade the language version of your code.

    These are marked as: Language versioned

  • Deprecations: The Dart SDK maintains compatibility for deprecated code, with a warning. Deprecations are then completely removed in a subsequent release, breaking any code that relies on the previous behavior.

    These are marked as: Deprecated / Removed

  • Experimental: Part of the release but not yet treated as stable in the SDK, and can break from one version to another. Experimental changes do not always have a corresponding breaking change issue, but may have more detail in the SDK changelog.

    These are marked: Experimental

If you have questions or concerns about any of these breaking changes, please comment on the breaking change issue linked from the relevant entry. To be notified about future breaking changes, join the Dart announce group.

3.6.0

#

Tentative
The following changes are expected to be included in the 3.6 stable release, but the final list will likely change before then. To reduce the potential impact of these changes, consider accounting for them before the 3.6 release.

Language

#

3.5.0

#

Language

#

Libraries

#

dart:core

#

dart:io

#

dart:js_interop

#

dart:typed_data

#

Runtime

#
  • Removed The Dart VM no longer supports unsound null safety.
    • The --no-sound-null-safety CLI option has been removed.
    • The Dart_NewListOf and Dart_IsLegacyType functions have been removed from the C API.
  • Removed The Dart_DefaultCanonicalizeUrl function has been removed from the C API.

3.4.0

#

Language

#

Libraries

#

dart:cli

#

dart:html, dart:indexed:db, dart:svg, dart:web_audo, dart:web_gl

#
  • Deprecated These libraries are now marked as legacy and will see less support in the future. New projects should prefer to use package:web and dart:js_interop. To learn more, check out Migrate to package:web.

dart:js

#
  • Deprecated This library is now marked as legacy and will see less support in the future. Usages should be migrated to dart:js_interop and dart:js_interop_unsafe. To learn more, check out /go/next-gen-js-interop.

dart:js_util

#
  • Deprecated This library is now marked as legacy and will see less support in the future. Usages should be migrated to dart:js_interop and dart:js_interop_unsafe. To learn more, check out /go/next-gen-js-interop.

dart:io

#

dart:typed_data

#

Tools

#

Production JavaScript compiler (dart2js)

#
  • Experimental Deprecated You should now specify a format to the --dump-info CLI option of either binary or json. The json format is deprecated and might be removed in a future Dart release.

Wasm compiler (dart2wasm)

#
  • Experimental Various dart compile wasm CLI arguments have been updated, removed, or replaced. To learn more, run dart compile wasm --verbose --help.

Runtime

#
  • Removed The Dart VM longer supports external strings. As a result, the Dart_IsExternalString, Dart_NewExternalLatin1String, and Dart_NewExternalUTF16String functions have been removed from the Dart C API.

3.3.0

#

SDK

#
  • Experimental Removed The following experiments are now retired as they were released in Dart 3 and are no longer necessary with a language version of 3.0 or greater. Configuration of them should be removed from analysis options, CLI commands, and IDE configurations.

    • patterns
    • records
    • class-modifers
    • sealed-class

Language

#

Libraries

#

dart:cli

#
  • Experimental Deprecated The waitFor function remains deprecated for another release and is set for removal in Dart 3.4.

dart:ffi

#

dart:html

#
  • Instead of using HttpRequest directly, it is now recommended to use package:http.

dart:io

#
  • Instead of using HttpClient directly, it is now recommended to use package:http.

dart:js_interop

#
  • Experimental JS types like JSAny have new compiler-specific representation types.
  • Experimental User-defined @staticInterop classes can no longer implement JSAny or JSObject. Usages should be migrated to JSObject.fromInteropObject or be defined as extension types.
  • Experimental JSArray and JSPromise now have generic parameters.
  • Experimental Various extension members were moved or renamed. To learn about the updated extensions, reference JSAnyUtilityExtension and JSAnyOperatorExtension.

dart:typed_data

#

dart:nativewrappers

#

Tools

#

Production JavaScript compiler (dart2js)

#

Wasm compiler (dart2wasm)

#

Analyzer

#
  • Experimental Invalid dart doc comment directives are now reported by the analyzer.

  • Due to improvements in type promotion, the following analyzer diagnostics might trigger on existing code that previously passed analysis:

    • unnecessary_non_null_assertion
    • unnecessary_cast
    • invalid_null_aware_operator

Linter

#
  • The iterable_contains_unrelated_type and list_remove_unrelated_type lints were removed. Consider migrating to the expanded collection_methods_unrelated_type lint.

  • The following lints are removed due to no longer being necessary with sound null safety. You should remove configuration of them from your analysis_options.yaml files and any ignore comments.

    • always_require_non_null_named_parameters
    • avoid_returning_null
    • avoid_returning_null_for_future

3.2.0

#

Language

#

Libraries

#

dart:cli

#

dart:convert

#

dart:developer

#
  • Deprecated The Service.getIsolateID method.

dart:ffi

#

dart:io

#

dart:js_interop

#
  • Experimental Removed JSNumber.toDart in favor of toDartDouble and toDartInt.
  • Experimental Removed Object.toJS in favor of Object.toJSBox.
  • Experimental Restricted external JS interop APIs using dart:js_interop to a set of allowed types.
  • Experimental Prohibited use of isNull and isUndefined on dart2wasm.
  • Experimental Changed typeofEquals and instanceof APIs to both return bool instead of JSBoolean. Also, typeofEquals now takes String instead of JSString.
  • Experimental Changed JSAny and JSObject types to only implementable, not extendable, by user @staticInterop types.
  • Experimental Changed JSArray.withLength to take int instead of JSNumber.

Tools

#

Development JavaScript compiler (DDC)

#

Production JavaScript compiler (dart2js)

#

Analyzer

#

3.1.0

#

Libraries

#

dart:async

#

dart:io

#

dart:js_interop

#
  • Experimental Removed ObjectLiteral; create an object literal with no named members using {}.jsify().

package:js

#
  • external @staticInterop members and external extension members can no longer be used as tear-offs. Declare a closure or a non-external method that calls these members, and use that instead.
  • external @staticInterop members and external extension members will generate slightly different JS code for methods that have optional parameters.

3.0.0

#

Language

#

Libraries

#
  • The following existing classes have been made mixin classes: Iterable, IterableMixin, IterableBase, ListMixin, SetMixin, MapMixin, LinkedListEntry, StringConversionSink.

dart:core

#

dart:async

#

dart:collection

#

dart:developer

#

dart:ffi

#
  • Experimental Deprecated The @FfiNative annotation is now deprecated. Usages should be updated to use the @Native annotation.

dart:html

#

dart:math

#
  • Language versioned The Random interface can only be implemented, not extended.

dart:io

#

2.19.0

#

Language

#

Libraries

#

dart:convert

#

dart:developer

#

dart:ffi

#

dart:io

#

dart:isolate

#
  • Reverted SendPort.send back to strict checks on contents of messages when sending messages between isolates that are not known to share the same code.

dart:mirrors

#

package:js

#

dart2js

#

2.18.0

#

Language

#

Libraries

#

dart:io

#

Tools

#

Dart command line

#

2.17.0

#

Libraries

#

dart:io

#

Tools

#

Dart command line

#

2.16.0

#

Libraries

#

dart:io

#

dart:isolate

#

Tools

#

Dart command line

#

2.15.0

#

Libraries

#

dart:io

#

dart:web_sql

#

dart:html

#

Tools

#

Dart command line

#

Dart VM

#

2.14.0

#

Libraries

#

dart:io

#
  • The setter callbacks .authenticate and .authenticateProxy in HttpClient must now accept a nullable realm argument (for pre-migrated null safe code).

dart:typed_data

#

Tools

#

Dart VM

#

Dart command line

#

dart2js

#

Dart Dev Compiler (DDC)

#

2.13.0

#

Libraries

#

package:js

#
  • No longer valid to use a String that matches an @Native annotation in an @JS() annotation for a non-anonymous JS interop class.

2.12.0

#

Language

#

Libraries

#

dart:ffi

#

Tools

#

Dart VM

#

Pub

#

2.10.0

#

Tools

#

Dart VM

#

2.9.0

#

Libraries

#

dart:convert

#

dart:html

#
  • CssClassSet.add() and CssClassSet.toggle now return false instead of null if the CssClassSet corresponds to multiple elements.

dart:mirrors

#

Tools

#

Dart VM

#

2.8.1

#

Language

#
  • Fixed an implementation bug where local variable inference would incorrectly use the promoted type of a type variable.
  • Fixed an implementation bug surrounding the clauses implements Function, extends Function, or with Function no longer having an effect since Dart 2.0.0.

Libraries

#

dart:async

#

dart:core

#

dart:ffi

#
  • Changed Pointer.asFunction() and DynamicLibrary.lookupFunction() to extension methods.

dart:io

#

Tools

#

Dart Dev Compiler (DDC)

#

We fixed several inconsistencies between DDC and Dart2JS so that users less frequently encounter code that is accepted by one compiler but then fails in the other.

  • Deleted the legacy (analyzer based) version of DDC.
  • Functions passed to JavaScript using the recommended package:js interop specification must now be wrapped with a call to allowInterop.
  • Constructors in @JS() classes must be marked with external.

dart2js

#
  • Corresponding type parameter bounds now only need to be mutual subtypes rather than structurally equal up to renaming of bound type variables and equating all top types.
  • Types are now normalized.
  • Constructors in @JS() classes must be marked with external.
  • Completely removed the --package-root flag, which was hidden and disabled in Dart 2.0.0.

2.7.1

#

2.7.0

#

Language

#

Libraries

#

dart:io

#
  • Added IOOverrides.serverSocketBind to aid in writing tests that wish to mock ServerSocket.bind.

2.6.0

#

Language

#

Libraries

#

dart:ffi

#
  • The API now makes use of static extension members.
  • Removed memory management Pointer.allocate and Pointer.free.
  • Pointer.offsetBy was removed, use cast and elementAt instead.

2.5.0

#

Libraries

#

dart:io

#

Tools

#

Pub

#

2.4.0

#

Language

#

Libraries

#

dart:isolate

#
  • Isolate.resolvePackageUri will always throw an UnsupportedError when compiled with dart2js or DDC.

dart:async

#

2.2.0

#

Libraries

#

package:kernel

#
  • The klass getter on the InstanceConstant class in the Kernel AST API has been renamed to classNode for consistency.
  • Updated Link implementation to utilize true symbolic links instead of junctions on Windows.

2.1.1

#

Libraries

#

dart:io

#

Tools

#

Dart VM

#

2.1.0

#

Language

#

Tools

#

dart2js

#
  • Duplicate keys in a const map are not allowed and produce a compile-time error.

2.0.0

#

Language

#

Libraries

#
  • Renamed constants in the core libraries from SCREAMING_CAPS to lowerCamelCase.
  • Added many new methods to core library classes that will need to be implemented if you implement the interfaces of these classes.
  • dart:isolate and dart:mirrors are no longer supported when using Dart for the web.

Tools

#

Pub

#