Getting Started
Install dart_mapper, configure build_runner, and write your first mapper.
Getting Started
Installation
Add dart_mapper to your pubspec.yaml:
dependencies:
dart_mapper: ^1.0.0
dev_dependencies:
build_runner: ^2.4.8
dart_mapper_generator: ^1.0.0
Run dart pub get to fetch packages.
1. Define your models
class AddressDto {
final String street;
final String city;
AddressDto(this.street, this.city);
}
class Address {
final String street;
final String city;
Address(this.street, this.city);
}
2. Create the mapper
Create a file (e.g., address_mapper.dart) with an abstract mapper class:
import 'package:dart_mapper/dart_mapper.dart';
part 'address_mapper.g.dart';
@Mapper()
abstract class AddressMapper {
Address toAddress(AddressDto dto);
AddressDto toDto(Address address);
}
The part directive links the generated file. The abstract methods declare the mapping contract — dart_mapper generates the implementations.
3. Run the generator
dart run build_runner build --delete-conflicting-outputs
This generates address_mapper.g.dart in the same directory.
4. Use the generated mapper
final mapper = AddressMapperImpl();
final address = mapper.toAddress(AddressDto('123 Main St', 'Springfield'));
final dto = mapper.toDto(address);
Field Renaming
When source and target field names differ, use @Mapping:
class PersonDto {
final String firstName;
PersonDto(this.firstName);
}
class Person {
final String name;
Person(this.name);
}
@Mapper()
abstract class PersonMapper {
@Mapping(target: 'name', source: 'firstName')
Person toPerson(PersonDto dto);
}
Build Configuration for Freezed / Built Value
If you use freezed or built_value, configure build ordering in build.yaml:
targets:
$default:
builders:
dart_mapper_generator:
options:
generate_for:
- lib/**
For freezed, ensure freezed runs before dart_mapper_generator:
global_options:
freezed:
runs_before:
- dart_mapper_generator
built_value_generator:
runs_before:
- dart_mapper_generator
Watching for Changes
During development, use watch mode to regenerate on save:
dart run build_runner watch --delete-conflicting-outputs
Next Steps
- @Mapping reference — all 9 field-mapping parameters
- Enum Mapping guide —
@ValueMappingand enum defaults - Freezed Support — immutable class mapping