generating-freezed-models

Freezed Guide (v3.2.x)

Goal

Generate immutable data classes, union types, and deep copyWith using Freezed v3.2.x. Complements Dart 3 sealed classes by adding copyWith, ==/hashCode, and JSON serialization via json_serializable.

Instructions

1. Dependencies and Environment Setup

Because Freezed relies heavily on code generation, ensure your pubspec.yaml is fully configured:

dependencies:
  freezed_annotation: ^3.2.5
  json_annotation: ^4.11.0 # If mutual conversion with JSON is required

dev_dependencies:
  build_runner: ^2.14.1
  freezed: ^3.2.5
  json_serializable: ^6.13.1 # If mutual conversion with JSON is required

2. Defining an Immutable Data Class

import 'package:freezed_annotation/freezed_annotation.dart';

// You MUST declare part files; the name must exactly match the current file
part 'user_model.freezed.dart';
part 'user_model.g.dart'; // If utilizing JSON serialization

// Freezed 3.x: prefer `sealed` modifier for exhaustive pattern matching
@freezed
sealed class UserModel with _$UserModel {
  const factory UserModel({
    required String id,
    required String name,
    @Default(18) int age,
    @JsonKey(name: 'is_active') @Default(true) bool isActive,
  }) = _UserModel;

  // Required for JSON serialization
  factory UserModel.fromJson(Map<String, Object?> json) => 
      _$UserModelFromJson(json);
}

After every model change, run dart run build_runner build -d.

3. Custom Getters and Methods

To add computed properties or methods, add a private parameterless constructor.

@freezed
abstract class Product with _$Product {
  // private constructor required to add custom methods
  const Product._();
  
  const factory Product({
    required double price,
    required double discountRate,
  }) = _Product;

  // Custom Getter
  double get discountedPrice => price * (1 - discountRate);

  // Custom Method
  bool isFree() => discountedPrice == 0;
}

4. Generic Types Support

@freezed
@JsonSerializable(genericArgumentFactories: true) // required for generic JSON parsing
sealed class PaginatedResponse<T> with _$PaginatedResponse<T> {
  const factory PaginatedResponse({
    required int currentPage,
    required int totalPages,
    required List<T> data,
  }) = _PaginatedResponse<T>;

  // fromJson for generics requires a conversion function parameter
  factory PaginatedResponse.fromJson(
    Map<String, dynamic> json,
    T Function(Object? json) fromJsonT,
  ) => _$PaginatedResponseFromJson(json, fromJsonT);
}