freezed | Dart package

Code generation for immutable classes that has a simple syntax/API without compromising on the features.
English | 한국어 | 简体中文 | 日本語 | Tiếng Việt
Welcome to Freezed, yet another code generator for data classes, tagged unions, nested classes and cloning.
To migrate from 2.0.0 to 3.0.0, see changelog and our migration guide.
Dart is awesome, but defining a "model" can be tedious. You have to:
Implementing all of this can take hundreds of lines, which are error-prone and affect the readability of your model significantly.
Freezed tries to fix that by implementing most of this for you, allowing you to focus on the definition of your model.
To use Freezed, you will need your typical build_runner/code-generator setup. First, install build_runner and Freezed by adding them to your pubspec.yaml file:
For a Flutter project:
This installs three packages:
If you plan on using Freezed in combination with json_serializable, recent versions of json_serializable and meta may require you to disable the invalid_annotation_target warning.
To do that, you can add the following to the analysis_options.yaml file at the root of your project:
To run the code generator, execute the following command:
Note that like most code-generators, Freezed will need you to both import the annotation (freezed_annotation) and use the part keyword on the top of your files.
As such, a file that wants to use Freezed will start with:
CONSIDER also importing package:flutter/foundation.dart. The reason being, importing foundation.dart also imports classes to make an object nicely readable in Flutter's devtool. If you import foundation.dart, Freezed will automatically do it for you.
Freezed offers two ways of creating data-classes:
Note As of Dart 3.13, primary constructors are a stable feature of Dart. This means that you no longer need to use freezed to generate primary constructors. But you can stick to using Freezed for ==/toString/etc:
Freezed implements Primary Constructors by relying on factory constructors. The idea is, you define a factory and Freezed generates everything else:
The following snippet defines a model named Person:
From this example, we can notice a few things:
It is necessary to annotate our model with @freezed (or @Freezed/@unfreezed, more about that later). This annotation is what tells Freezed to generate code for that class.
We must also apply a mixin with the name of our class, prefixed by _$. This mixin is what defines the various properties/methods of our object.
When defining a constructor in a Freezed class, we should use the factory keyword as showcased (const is optional). The parameters of this constructor will be the list of all properties that this class contains. Parameters don't have to be named and required. Feel free to use positional optional parameters if you want!
Sometimes, you may want to manually define methods/properties in our classes. But you will quickly notice that if you try to use primary constructors:
then it will fail with the error The non-abstract class _$_Person is missing implementations for these members:.
For that to work, we need to define a private empty constructor. That will enable the generated code to extend/subclass our class, instead of implementing it (which is the default, and only inherits type, and not properties or methods):
Dart does not allow adding assert(...) statements to a factory constructor. As such, to add asserts to your Freezed classes, you will need the @Assert decorator:
Alternatively, you can specify a MyClass._() constructor:
Similarly to asserts, Dart does not allow "redirecting factory constructors" to specify default values.
As such, if you want to specify default values for your properties, you will need the @Default annotation:
NOTE: If you are using serialization/deserialization, this will automatically add a @JsonKey(defaultValue: <something>) for you.
If using @Default is not enough, you have two options:
The latter is particularly helpful when writing large models, as this doesn't require writing a lot of code just for one default values.
One example would be the following:
In this example, the field time is defaulting to DateTime.now().
You may want to have your Freezed class extend another class. Unfortunately, factory does not allow specifying super(...).
As such, one workaround is to specify the MyClass._() again, similarly to how we used it for non-constant default values. Here's an example:
This syntax gives full control over inheritance. Of course, you can also opt-out of factory constructors and write normal classes. See Classic Classes.
In general, this workaround makes more sense for Unions, where we have more than one factory constructor.