Dart SDK Changelog & Version Feature Guide (Dart 1.x to Modern Dart 3.x)

--enable-experiment

🎯 Parent Guide: How to Find the

minSdk

for Any Dart Feature or API

minSdk

pubspec.yaml

1. Language Version vs. SDK Version

• Language Version (

  major.minor

  ): In

  pubspec.yaml

  , the lower bound of

  environment.sdk

  (for example

  ^3.13.0

  or

  >=3.12.0 <4.0.0

  ) dictates which language grammar and compiler semantics are enabled.
  • Patch numbers (

    .1

    ,

    .2

    ) do not affect language grammar.
  • Using a Dart 3.13 feature (like Primary Constructors) requires

    sdk: '^3.13.0'

    .
• Core Library APIs: Methods and classes (for example

  Future.pause

  ,

  List.unmodifiableOf

  ) are added in specific SDK versions.
• Per-file override: A file can specify

  // @dart = 3.12

  on line 1 to force an earlier language version.

2. Fast

minSdk

Language Feature Matrix

3.13.0

class Point(var int x, var int y);

this : assert(...)

3.13.0

new(this.x);

factory clone(...) => ...;

3.12.0

Point({required this._x, required this._y});

_

3.7.0

var (_, b) = pair;

void fn(int _, int _)

3.7.0

3.6.0

1_000_000

0x4000_0000

0.000_001

3.3.0

extension type Meters(int value) {}

3.2.0

if (_privateFinalField != null) { ... }

3.0.0

(int, String) pair = (1, 'a');

3.0.0

var (a, b) = pair;

switch (val) { case ... }

3.0.0

var s = switch (e) { 0 => 'a', _ => 'b' };

3.0.0

if (json case {'id': int id}) ...

3.0.0

sealed class State {}

base

interface

final

3.0.0

interface class Api {}

final class Token {}

3.0.0

2.17.0

SubClass(super.name, {super.key});

2.17.0

enum Status { ok(200); final int c; const Status(this.c); }

2.17.0

fn(1, named: 'a', 2);

2.15.0

List.filled

Point.new

>>>

2.14.0

int result = a >>> b;

typedef

2.13.0

typedef JsonMap = Map<String, dynamic>;

?

late

!

2.12.0

2.7.0

extension on String { ... }

...

...?

2.3.0

[...list1, ...?maybeList]

if

for

2.3.0

[if (cond) a, for (var x in l) x * 2]

new

2.0.0

⚡ Subskill Spotlights

Subskill: Augmentations & Static Metaprogramming (Macros)

• Augmentation Syntax: Declare

  augment class

  ,

  import augment

  , and wrap methods using

  augmented()

  .
• Macro Phases: Understand Type, Declaration, and Definition macro execution in the analysis server.
• In-Memory Code Gen: Eliminate

  build_runner

  with zero-disk

  .g.dart

  pollution. 👉 Read the full Macros & Augmentations Guide.

Subskill: Experimental Features & Compiler Flags (

--enable-experiment

)

• Enabling Experiments: Configure

  analysis_options.yaml

  (

  analyzer.enable-experiment

  ), CLI flags (

  dart --enable-experiment=...

  ), and VS Code settings.
• Release Pipeline: Understand the graduation path across Beta preview, Stable-gated, and Stable-ungated tiers. 👉 Read the full Experimental Features Guide.

Subskill: Rescuing Legacy Codebases (Dart 1.x & Pre-2.12 to Modern Dart)

• Sound Null Safety Migration: Transform

  @required

  annotations, uninitialized nullable fields, and defensive runtime assertions.
• Dependency Upgrades: Modernize

  pubspec.yaml

  environment bounds and replace deprecated legacy packages (

  pedantic

  ,

  tuple

  , etc.). 👉 Read the full Legacy Codebase Rescue Guide.

📚 Table of Contents (TOC) & Version Archive

augment

augmented()

import augment

@JsonCodable()

--enable-experiment

NativeFinalizer.callback

this

new

factory

Future.pause

Point({this._x})

RegExp

dart run <pkg>@<ver>

pkgs/*

dart pub cache gc

dart install

@Deprecated

@docImport

Iterable.withIterator

_

1_000_000

dart pub bump

🛠️ Recommended Runbooks

1. Working with Augmentations & Macros

1. Review Macros & Augmentations Guide.
2. Wire original files with

   import augment 'foo.g.dart';

   and augmentation files with

   augment library 'foo.dart';

   .
3. Use

   augment class

   ,

   augment void method()

   , and call

   augmented()

   to wrap original logic.

2. Working with Experimental Feature Flags

1. Check if the feature has already graduated to stable in the active SDK before adding a flag.
2. If experimental, configure

   analysis_options.yaml

   under

   analyzer.enable-experiment: [name]

   .
3. Pass

   --enable-experiment=name

   to

   dart run

   ,

   dart test

   ,

   flutter run

   , and

   flutter test

   .
4. Ensure experimental code is isolated so production packages remain publishable on pub.dev.

3. Modernizing / Rescuing a Legacy Codebase

1. Check current language version from

   pubspec.yaml

   environment block.
2. If pre-2.12, read the Legacy Rescue Guide.
3. Execute the 4-stage pipeline: syntax cleanup → sound null safety → dependency bump (

   sdk: ^3.5.0

   or

   ^3.13.0

   ) → Dart 3 modernization.

4. Answering "What's New in Dart X.Y"

1. Identify the requested version.
2. Read the corresponding reference document under

   references/

   .
3. Provide:
   • Language syntax changes with before/after code snippets.
   • Core library additions (

     dart:core

     ,

     dart:async

     ,

     dart:io

     ,

     dart:js_interop

     ,

     dart:isolate

     ,

     dart:ffi

     ).
   • Tooling and CLI features (

     dart analyze

     ,

     dart format

     ,

     dart pub

     ,

     dart build

     ).
   • Breaking changes and migration instructions.

5. Answering "How to find minSdk for X"

1. Check the Language Feature Matrix and How to Find minSdk Guide.
2. Specify the exact lower bound SDK constraint for

   pubspec.yaml

   (for example

   sdk: '^3.13.0'

   ).
3. Explain if the feature is a language grammar feature (requiring language version update) or a core library API.
4. Show how to verify using

   dart analyze

   .