/dart-use-primary-constructors

name: dart-use-primary-constructors
description: >
  Help users write syntactically and semantically correct primary constructors in Dart, and migrate/use the new constructor syntax, empty-body semicolon syntax, in-body initializer list syntax, and abbreviated concise constructor syntax.
metadata:
  model: models/gemini-3.1-pro-preview
  last_modified: Thu, 09 Jul 2026 23:13:25 GMT

Dart Primary Constructors & New Constructor Syntax Skill

Use this skill when helping users write, refactor, or debug code using Dart's **Primary Constructors** feature.

Dart Version Requirements

• **Dart 3.13 and above**: Primary constructors are enabled by default.
• **Dart 3.12**: The feature is available but experimental. Users must explicitly enable the experiment flag `primary-constructors` via `--enable-experiment=primary-constructors` or in `analysis_options.yaml`:

analyzer:
  enable-experiment:
    - primary-constructors

• **Dart 3.11 and earlier**: Primary constructors are not supported.

---

1. Overview

Primary Constructors allow developers to declare a non-redirecting generative constructor as well as a set of instance variables directly in the class header. This significantly reduces boilerplate and improves code readability.

Key Benefits

• Combines field declaration, parameter declaration, and initialization into a single declaration known as a declaring parameter declaration.
• Enables safe reference to constructor parameters in non-late field initializers (Primary Initializer Scope).
• Allows empty declaration bodies to be represented concisely with a semicolon (`;`).
• Introduces abbreviated concise syntax for in-body constructors.

---

2. Syntax Reference

2.1 Basic Class Header Syntax

To declare a primary constructor, place a parameter list immediately after the type name (and optional type parameters):

// Declares fields x and y, and a generative constructor Point(this.x, this.y)
class Point(var int x, var int y);

// Declares final fields
class PointFinal(final int x, final int y);

2.2 Declaring, Initializing, and Plain Parameters

A primary constructor parameter list distinguishes between three types of parameters: 1. **Declaring Parameters**: Indicated by the `var` or `final` modifier (e.g., `final int x`). They implicitly create a corresponding instance field in the class. 2. **Initializing Parameters**: Indicated by the `this.` or `super.` prefix (e.g., `this.x` or `super.x`). They initialize an existing field or a super constructor parameter, respectively. 3. **Regular Parameters**: Declared without modifiers (e.g., `int y`). They do not become fields and are only available during initialization (e.g., in field initializers or the `this :` initializer list in the class body).

// `x` is a field and a parameter because it has the keyword `final`. In particular, we can use the name `x` in the initializer list in the in-body part of the primary constructor. 'y' is a only parameter because it has neither of the keywords `final` or `var`, but `y` is passed to the super constructor via the `this :` initializer list.
class C(final int x, int y) extends Base {
  this : super(y);
}

Declaring parameters and initializing parameters are two ways of achieving the same goal: declaring a class with instance fields which are set in the constructor. Regular parameters are different in that their values are not automatically routed to an instance field.

2.3 Constant Primary Constructors

To make a primary constructor `const`, place the `const` keyword before the class/type name in the declaration header:

class const Point(final int x, final int y);
extension type const Ext(int x);
enum const MyEnum(final int x) {
  entry(1);
}

2.4 Extension Types

Extension types **must** use primary constructors.

• The single parameter in the header is the representation field.
• The representation variable cannot use the `var` modifier (using `var` triggers the `representation_field_modifier` error).
• The representation variable can optionally use the `final` modifier. If `final` is not present then it is inferred; that is, the parameter is declaring whether or not it's explicitly `final`.

2.5 Empty Body Semicolon Shorthand (`;`)

When a class, mixin class, mixin, extension or extension type has an empty body, the `{}` braces can be replaced by a semicolon (`;`):

class C(int x);
mixin class MC;
extension type ET(int x);
mixin M;
extension Ext on C;

2.6 The In-Body Part of a Primary Constructor (`this ...`)

If a primary constructor requires assertions or custom field initializations, they can be declared in the body using the `this :` syntax:

class Point(var int x, var int y) {
  // Initializer list in class body
  this : assert(x >= 0), y = y * 2;
}

You can also write a constructor body with this syntax (`this {...}`).

2.7 Abbreviated Concise Constructor Syntax

For constructors declared within the class body, the class name can be omitted and replaced with the `new` or `factory` keywords:

| Traditional Syntax | Abbreviated Concise Syntax | | :--- | :--- | | `MyClass() {}` | `new() {}` | | `MyClass.name() {}` | `new name() {}` | | `const MyClass();` | `const new();` | | `const MyClass.name();` | `const new name();` | | `factory MyClass() => ...` | `factory() => ...` | | `factory MyClass.name() => ...` | `factory name() => ...` |

---

3. Semantics & Scoping Rules

3.1 Primary Initializer Scope

When a primary constructor is declared, its formal parameters are introduced into the **Primary Initializer Scope**. This scope is the current scope for non-late field initializers in the class body and the primary constructor's initializer list (after `this :`). This allows non-late fields to reference constructor parameters directly during declaration:

  class DeltaPoint(final int x, int delta) {
    // 'x' and 'delta' are in scope here
    final int y = x + delta;