randalschwartz Dart SDK Changelog & Version Feature Guide (Dart 1.x to Modern Dart 3.x)
This skill provides an authoritative, structured guide to Dart language features, core library APIs, tooling changes, version requirements, experimental feature flags (--enable-experiment), static metaprogramming (Macros & Augmentations), and legacy modernization runbooks sourced directly from the official Dart SDK CHANGELOG.
🎯 Parent Guide: How to Find the minSdk for Any Dart Feature or API
When writing or reviewing Dart code, selecting the correct minimum SDK lower bound (minSdk) in pubspec.yaml is essential to ensure syntax and core APIs compile across target environments.
1. Language Version vs. SDK Version
- Language Version (
major.minor): Inpubspec.yaml, the lower bound ofenvironment.sdk(for example^3.13.0or>=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'.
- Patch numbers (
- 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.12on line 1 to force an earlier language version.
2. Fast minSdk Language Feature Matrix
| Feature / Syntax | Minimum SDK | Example Syntax | Reference |
|---|---|---|---|
| Primary Constructors | 3.13.0 |
class Point(var int x, var int y); / this : assert(...) |
3.13 Guide |
| Constructor Keyword Shorthands | 3.13.0 |
new(this.x); / factory clone(...) => ...; |
3.13 Guide |
| Private Named Parameters | 3.12.0 |
Point({required this._x, required this._y}); |
3.12 Guide |
Wildcard Variables (_) |
3.7.0 |
var (_, b) = pair; / void fn(int _, int _) |
3.7 Guide |
| Type Inference Using Bounds | 3.7.0 |
Inferred types respect type parameter bounds | 3.7 Guide |
| Digit Separators | 3.6.0 |
1_000_000, 0x4000_0000, 0.000_001 |
3.6 Guide |
| Extension Types | 3.3.0 |
extension type Meters(int value) {} |
3.0-3.5 Guide |
| Private Field Promotion | 3.2.0 |
if (_privateFinalField != null) { ... } |
3.0-3.5 Guide |
| Records (Tuples) | 3.0.0 |
(int, String) pair = (1, 'a'); |
3.0-3.5 Guide |
| Pattern Matching & Destructuring | 3.0.0 |
var (a, b) = pair; / switch (val) { case ... } |
3.0-3.5 Guide |
| Switch Expressions | 3.0.0 |
var s = switch (e) { 0 => 'a', _ => 'b' }; |
3.0-3.5 Guide |
| If-Case Statements & Elements | 3.0.0 |
if (json case {'id': int id}) ... |
3.0-3.5 Guide |
| Sealed Classes & Exhaustiveness | 3.0.0 |
sealed class State {} |
3.0-3.5 Guide |
Class Modifiers (base, interface, final) |
3.0.0 |
interface class Api {} / final class Token {} |
3.0-3.5 Guide |
| 100% Sound Null Safety Enforced | 3.0.0 |
Non-null-safe mode disallowed | 3.0-3.5 Guide |
| Super-Initializer Parameters | 2.17.0 |
SubClass(super.name, {super.key}); |
Dart 2 Milestones |
| Enhanced Enums | 2.17.0 |
enum Status { ok(200); final int c; const Status(this.c); } |
Dart 2 Milestones |
| Named Arguments Anywhere | 2.17.0 |
fn(1, named: 'a', 2); |
Dart 2 Milestones |
| Constructor Tear-Offs | 2.15.0 |
List.filled, Point.new |
Dart 2 Milestones |
Triple-Shift Operator (>>>) |
2.14.0 |
int result = a >>> b; |
Dart 2 Milestones |
Generic Type Aliases (typedef) |
2.13.0 |
typedef JsonMap = Map<String, dynamic>; |
Dart 2 Milestones |
Sound Null Safety (?, late, !) |
2.12.0 |
Sound static non-nullable types | Dart 2 Milestones |
| Extension Methods | 2.7.0 |
extension on String { ... } |
Dart 2 Milestones |
Spread Operators (..., ...?) |
2.3.0 |
[...list1, ...?maybeList] |
Dart 2 Milestones |
Collection if and for |
2.3.0 |
[if (cond) a, for (var x in l) x * 2] |
Dart 2 Milestones |
Sound Type System & Optional new |
2.0.0 |
Static sound types replace dynamic checks | Dart 2 Milestones |
👉 For deep-dive and verification procedures, see How to Find minSdk and the Full Version Matrix.
⚡ Subskill Spotlights
Subskill: Augmentations & Static Metaprogramming (Macros)
- Augmentation Syntax: Declare
augment class,import augment, and wrap methods usingaugmented(). - Macro Phases: Understand Type, Declaration, and Definition macro execution in the analysis server.
- In-Memory Code Gen: Eliminate
build_runnerwith zero-disk.g.dartpollution. 👉 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
@requiredannotations, uninitialized nullable fields, and defensive runtime assertions. - Dependency Upgrades: Modernize
pubspec.yamlenvironment bounds and replace deprecated legacy packages (pedantic,tuple, etc.). 👉 Read the full Legacy Codebase Rescue Guide.
📚 Table of Contents (TOC) & Version Archive
| Release / Guide | Focus Area | Key Additions | Reference Document |
|---|---|---|---|
| Macros & Augmentations | Metaprogramming | augment, augmented(), import augment, @JsonCodable(), 3-phase macro pipeline |
Macros & Augmentations Guide |
| Experimental Features | Compiler Flags | --enable-experiment, Beta preview vs stable-gated release tiers, graduation matrix |
Experiments Guide |
| Legacy Rescue | Migration Runbook | Dart 1.x/2.x to Modern 3.x modernization pipeline, null-safety bridge, package replacements | Rescue Guide |
| Dart 3.14 | FFI & JS Interop | NativeFinalizer.callback, fast primitive JS array conversions |
3.14 Reference |
| Dart 3.13 | Language & Runtime | Primary constructors, this constructor body, new/factory shorthands, Future.pause, synchronous isolates |
3.13 Reference |
| Dart 3.12 | Language & Tooling | Private named parameters (Point({this._x})), RegExp spans, dart run <pkg>@<ver> |
3.12 Reference |
| Dart 3.11 | Platform & Pub | Windows Unix domain sockets, Workspace globs (pkgs/*), dart pub cache gc |
3.11 Reference |
| Dart 3.10 | Extensibility & CLI | Analyzer plugins stable, Hooks (native assets) stable, dart install, @Deprecated constructors |
3.10 Reference |
| Dart 3.9 | Analysis & Pub | AOT analysis server, git tag version solving, null-safety assumptions in flow analysis | 3.9 Reference |
| Dart 3.8 | Formatter & Docs | Doc imports (@docImport), tall formatter trailing comma preservation, Iterable.withIterator |
3.8 Reference |
| Dart 3.7 | Language & Formatter | Wildcard variables (_), inference using bounds, tall style formatter default, legacy web deprecations |
3.7 Reference |
| Dart 3.6 | Language & Pub | Digit separators (1_000_000), Pub workspaces, dart pub bump |
3.6 Reference |
| Dart 3.0 – 3.5 | Foundation & Major Features | Records, Patterns, Switch Expressions, Sealed Classes, Class Modifiers, Extension Types, Field Promotion, Wasm | 3.0–3.5 Reference |
| Dart 2.0 – 2.19 | Historical Milestones | Sound Null Safety (2.12), Enhanced Enums & Super-Params (2.17), Extension Methods (2.7), Spreads (2.3), Sound Type System (2.0) | Dart 2 Milestones |
🛠️ Recommended Runbooks
1. Working with Augmentations & Macros
- Review Macros & Augmentations Guide.
- Wire original files with
import augment 'foo.g.dart';and augmentation files withaugment library 'foo.dart';. - Use
augment class,augment void method(), and callaugmented()to wrap original logic.
2. Working with Experimental Feature Flags
- Check if the feature has already graduated to stable in the active SDK before adding a flag.
- If experimental, configure
analysis_options.yamlunderanalyzer.enable-experiment: [name]. - Pass
--enable-experiment=nametodart run,dart test,flutter run, andflutter test. - Ensure experimental code is isolated so production packages remain publishable on pub.dev.
3. Modernizing / Rescuing a Legacy Codebase
- Check current language version from
pubspec.yamlenvironment block. - If pre-2.12, read the Legacy Rescue Guide.
- Execute the 4-stage pipeline: syntax cleanup → sound null safety → dependency bump (
sdk: ^3.5.0or^3.13.0) → Dart 3 modernization.
4. Answering "What's New in Dart X.Y"
- Identify the requested version.
- Read the corresponding reference document under
references/. - 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"
- Check the Language Feature Matrix and How to Find minSdk Guide.
- Specify the exact lower bound SDK constraint for
pubspec.yaml(for examplesdk: '^3.13.0'). - Explain if the feature is a language grammar feature (requiring language version update) or a core library API.
- Show how to verify using
dart analyze.