Freezed
Code generation library for immutable data classes, union types (sealed classes), and pattern matching in Dart/Flutter. With a @freezed annotation and build_runner, Freezed generates: copyWith(), operator==, hashCode, toString(), fromJson/toJson (with json_serializable), and exhaustive pattern matching for union types. Eliminates boilerplate for data models, BLoC states, and API response types. Made by the same author as Riverpod.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
Compile-time code generation — no runtime security surface. Generated code is auditable. Immutability prevents accidental state mutation security issues.
⚡ Reliability
Best When
You're building Flutter apps with complex data models or state union types and want compile-time safety with exhaustive pattern matching and zero-boilerplate immutable classes.
Avoid When
Your data models are simple with few fields, or you want to avoid adding build_runner to your build process. Simple Dart classes work fine for basic use cases.
Use Cases
- • Generate immutable data model classes for agent API responses with copyWith() and JSON serialization without writing boilerplate
- • Define exhaustive union types for agent state machines — Freezed sealed classes enable exhaustive pattern matching that the Dart compiler enforces
- • Create value objects for agent domain models with structural equality, toString, and copyWith without implementing each method manually
- • Model BLoC/Riverpod states as Freezed unions — AgentState.loading(), AgentState.success(data), AgentState.error(message) with exhaustive when/map
- • Generate JSON serialization for complex nested data structures using @freezed with @JsonSerializable for complete fromJson/toJson support
Not For
- • Mutable data classes — Freezed generates immutable classes; use regular Dart classes or built_value for mutable models
- • Non-Dart languages — Freezed is Dart-only; use Kotlin data classes, Swift structs, or TypeScript interfaces for other languages
- • Teams that prefer writing boilerplate manually — Freezed requires build_runner code generation workflow; adds build step complexity
Interface
Authentication
Code generation library — no auth concepts.
Pricing
Freezed is MIT licensed and free. Maintained by Remi Rousselet.
Agent Metadata
Known Gotchas
- ⚠ build_runner must be run after every annotation change — new fields, modified union cases, or annotation changes require 'dart run build_runner build'; stale generated files cause confusing compile errors
- ⚠ Generated .freezed.dart files should be committed or added to .gitignore — team must agree on strategy; committing avoids build step in CI, gitignoring requires build step in CI pipeline
- ⚠ Union type when() vs map() — when() has callbacks for all cases including default, map() is exhaustive without default; map() is preferred for compile-time exhaustiveness enforcement
- ⚠ copyWith with null values — Freezed's copyWith uses a special @Default annotation for nullable fields; setting a nullable field to null via copyWith requires the special copyWith(field: null) pattern
- ⚠ Deeply nested Freezed objects require manual deep copyWith — copyWith only copies one level; changing nested Freezed objects requires chaining: obj.copyWith(nested: obj.nested.copyWith(field: value))
- ⚠ Freezed + json_serializable version coupling — Freezed generates json_serializable annotations; version mismatches between freezed, freezed_annotation, and json_serializable cause build errors
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for Freezed.
Scores are editorial opinions as of 2026-03-06.