Every Kotlin codebase has that file. Forty lines of id = id, name = name, email = email that nobody wanted to write and nobody wants to review. Kraft deletes it:
- fun User.toUserDto(): UserDto = UserDto(
- id = id,
- name = name,
- email = email,
- )
+ @MapConfig(source = User::class, target = UserDto::class)
+ object UserMapper
val dto = user.toUserDto() // generated at compile time
When the models differ, add one line per rule, directly on the object:
data class UserDto(val name: String, val mail: String, val internalNotes: String)
data class User(val fullName: String, val email: String, val currency: String, val internalNotes: String = "")
@MapConfig(source = UserDto::class, target = User::class)
@FieldMapping(source = "name", target = "fullName")
@FieldMapping(source = "mail", target = "email")
@MapIgnoreField("internalNotes")
object UserMapper {
@MapConstant val currency = "HUF" // generated: currency = UserMapper.currency
}
That's the whole mapper. Kraft is a KSP processor that generates type-safe extension functions between your data classes — plain, readable Kotlin you can inspect in build/generated. No reflection, no runtime library, nothing to ship.
Why Kraft
- Breaks at build time, not in production — rename a property and the generated mapper stops compiling right there, instead of passing
null around at runtime.
- Zero runtime cost — the generated code is exactly what you'd have written by hand, minus the writing.
- Multiplatform from the start — annotations live in
commonMain; JVM, Android, iOS, JS, and WasmJs all work.
- Escape hatches everywhere — renames, ignores, custom converters, enum tables: when your models disagree, you override one property, not the whole mapper.
Features
Mapping
- Automatic property matching — same-name properties mapped without configuration
- Field renaming —
@MapField, or flat @FieldMapping lines on the @MapConfig object, for cross-name mapping
- Nested objects — auto-detected when types differ, including renamed properties
- Collections —
List<T> and Set<T> with nested element mapping
- Value classes — typed IDs like
UserId(val value: String) are wrapped and unwrapped automatically, including nullable and collection properties
- Enum mapping —
@MapEnum with auto-matching and custom entry pairs
- Reverse mapping —
@MapReverse generates the inverse mapper automatically
Control & customization
- Custom converters —
@MapUsing for property-source or whole-source transformations
- Global converters —
@KraftConverter on a top-level extension is auto-discovered across the module and the classpath, with @OptIn markers propagated onto the generated mapper
- Ignore rules —
@MapIgnore and @MapIgnoreField with directional control
- Constant values —
@MapConstant fills a target property from a member of the @MapConfig object
- Configuration objects —
@MapConfig for mapping without modifying data classes
- Layer-aware aliases — register
Dto / Domain / Entity sides via the kraft { } Gradle DSL to emit short .toDomain() / .toEntity() extensions alongside the verbose mappers
Platform & tooling
- Kotlin Multiplatform — annotations work on JVM, iOS, JS, and WasmJs
- Plugin SPI — implement
MapperGeneratorProvider to plug in your own code generator
Requirements
- Kotlin 2.2+ — built against 2.2.21; CI also runs the plugin suite on Kotlin 2.4.10 (Android-tagged tests excluded there; Android is covered by the Gradle 8.13 / 9.5.1 legs and a dedicated AGP 9 job)
- KSP 2 — built against 2.3.3; CI runs a compatibility matrix (2.3.3 and 2.3.9) plus a weekly probe against the newest KSP on Maven Central, so newer KSP 2 releases are tested rather than assumed (KSP 1-era versions are not supported)
- Gradle 8.13+ — CI covers 8.13, 9.5.1 and 9.6.1
- JDK 17+ build toolchain — the processor runs at compile time only
Kraft runs entirely at build time; the generated mappers are plain Kotlin and the annotations target JVM 1.8, so legacy apps on older runtimes are supported — see Compatibility and legacy projects.
Installation
Kraft is published to Maven Central under the com.blu3berry.kraft group (latest version shown in the badge above). Make sure mavenCentral() is in your repositories { } block.
The Gradle plugin is the one-line setup for Kotlin Multiplatform, JVM, and Android modules — it adds the version-aligned dependencies and all wiring:
// build.gradle.kts
plugins {
kotlin("multiplatform") // or kotlin("jvm") / kotlin("android")
id("com.google.devtools.ksp") version "<ksp-version>"
id("com.blu3berry.kraft") version "<version>"
}
Optional configuration goes through the typed kraft { } extension:
kraft {
side("dto") { packagePattern = "com.example.dto.**" } // emits .toDto() aliases
side("domain") { packagePattern = "com.example.domain.**" } // emits .toDomain() aliases
}
Prefer explicit control, or need the legacy-project integration patterns? See Getting Started for manual wiring.
Documentation
Full guides for every feature live on the docs site:
Quick Reference
| Annotation | Purpose | Placement |
|---|
@MapConfig | Standalone mapping config | On object |
@MapFrom | Map from source class | On target data class |
@MapTo | Map to target class | On source data class |
@MapField | Rename a property | On property in @MapFrom/@MapTo class |
@MapNested | Deprecated — auto-detected | On property in @MapFrom/@MapTo class |
@MapIgnore | Skip a property | On property (must have default value) |
@MapUsing | Custom converter function | On function in @MapConfig object |
@KraftConverter | Globally discoverable converter | On top-level extension function |
@MapEnum | Enum-to-enum mapping | On object |
@MapReverse | Generate inverse mapper | On class or @MapConfig object |
aliasEmitMode | Per-mapper alias control (AliasEmitMode enum) | Parameter on @MapConfig and @MapEnum |
ConverterDirection | Direction selector for @MapUsing (AUTO / FORWARD / REVERSE) | Parameter on @MapUsing(direction = …) |
IgnoreSide | Direction selector for @MapIgnoreField (TARGET / SOURCE / BOTH) | Parameter on @MapIgnoreField(direction = …) |
@FieldMapping | Config-level rename (repeatable) | On the @MapConfig object, or in @MapConfig.fieldMappings |
@MapConstant | Fixed target value ( once, per call) |
License
Copyright Kraft Contributors
Licensed under the Apache License, Version 2.0
See LICENSE for the full text.
