Open-source project
riok/mapperly avatar
riok/mapperly

Mapperly: a .NET source generator where every recent release is a preview tag

A .NET source generator for generating object mappings. No runtime reflection.

4,206 stars234 forksC#Apache-2.0

At a glance

What is it?
Mapperly writes object mapping code at build time from a partial class with an attribute, so there is no runtime reflection and the output can be read. Two release channels run in parallel, the recent tags are all 5.0.0 prereleases, and only the latest stable build is fully supported.
Who is it for?
Use Mapperly when you want mapping code that a person can read and a debugger can step into, rather than a mapper that resolves types at run time. Install the stable channel for anything you ship, because the support policy covers only the latest stable release, and treat the next channel as a test surface where breaking changes are expected between prereleases.
Can I use it commercially?
Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 2 days ago.
What is it written in?
Mainly C#, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • riok/mapperly4,206 ★ · +30
Star history
Repository2026-09-232026-11-15
riok/mapperly4.2k4.2k

30 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Every recent release is a next-channel tag

The three most recent releases are v5.0.0-next.12 from October 28, 2026, v5.0.0-next.11 from September 1, and v5.0.0-next.10 from July 13.

All three are prereleases of the same version, which is a direct consequence of how the project distributes itself. There are two channels. The stable channel carries production-ready releases, is subject to semantic versioning, and only breaks in major version bumps. The next channel carries preview releases with upcoming features, may contain breaking changes, and is explicitly not subject to semantic versioning.

So the tag list is not a record of what most users are running. A team on the stable channel is on whatever stable release is current, while the 5.0 line accumulates prereleases for people testing the next major version. The last push to the repository is dated November 2, 2026, so both lines are moving.

The practical consequence is that a version comparison across channels tells you nothing. Pick a channel and compare only within it.

Only the latest stable release is fully supported

The support policy is two sentences and both matter.

Only the latest version released on the stable channel is fully supported. So the previous stable release, the one before it, and every preview build are outside that promise, and a production application should expect to move forward rather than sit on an older patch.

The second sentence is about platforms rather than versions: the project says it strives to support all .NET versions that are currently supported by Microsoft. There is no list of target frameworks in the README and no pinned SDK version for consumers, which means the support surface follows whatever the platform vendor currently supports.

The generated code is meant to be read

The argument for a source generator over a run-time mapper is made in two steps, and the second step is the interesting one.

The first is overhead. Because Mapperly creates the mapping code at build time, the claim is minimal overhead at run time.

The second is legibility. The generated code is described as perfectly readable, which means you can verify the generated mapping code easily. That is the part a run-time mapper cannot offer: there is no artefact to open, only a configuration to trust.

So the artefact matters as much as the behaviour. When a mapping does the wrong thing, the answer is to look at the code the compiler produced rather than to trace an interceptor chain. The repository description makes the same point in one line, a source generator for generating object mappings, with no run-time reflection.

The cost sits on the other side of the trade. Generation happens during the build, so a project with a large model surface pays for it in build time, and an incremental build has to decide when a mapping is stale.

The mapper is a partial class with an attribute

A mapper is declared as a partial class carrying the abstraction attribute, and the methods you declare are what gets implemented.

csharp
// Mapper declaration
[Mapper]
public partial class CarMapper
{
    public partial CarDto CarToCarDto(Car car);
}

// Mapper usage
var mapper = new CarMapper();
var car = new Car { NumberOfSeats = 10, ... };
var dto = mapper.CarToCarDto(car);
dto.NumberOfSeats.ShouldBe(10);

Nothing else is needed. You write the signature, the generator supplies the body, and the partial class is what lets it add an implementation to a class you already declared.

The usage is unremarkable: construct the mapper, call the generated method, get the destination object. The last line of the sample is an assertion on a mapped property, and it is there to make the point that the property arrived intact rather than to demonstrate a test framework.

The repository pins its SDK and ships benchmarks and samples

The tree shows how a source generator project is put together. There is a solution file in the newer XML solution format rather than the classic format, a global.json that pins the SDK used for the build, and a Directory.Build.props for shared MSBuild properties.

Formatting is handled by CSharpier, with its configuration file and its ignore file at the root, alongside an editorconfig for per-editor rules. There is a .husky directory, so commit hooks are installed locally rather than being a convention.

Three directories are about verification. test/ holds the test suite, benchmarks/ holds performance measurements, and samples/ holds a runnable sample project. The benchmarks matter more than usual here, because the whole argument for a generator is that run-time cost went down, and a repository that claims minimal overhead without a benchmark project would be asking you to take it on faith.

Documentation sources sit in docs/ as well as being published to the project site, and a CONTRIBUTING.md sits at the repository root.

Breaking changes are listed per major version

Upgrading is handled with a documentation category rather than a changelog convention: the site publishes a list of breaking changes for each major version together with upgrade guides.

That structure fits the two-channel model. Within the stable channel, semantic versioning means a major bump is the only breaking event, so a per-major list is complete.

Which channel you are on decides how much you need that page. A production project on the stable channel reads it once per major version.

The same logic applies to the support policy. Because only the newest stable release is fully supported, the upgrade guide and the support window arrive together: you are expected to move when the major version moves.

Consulting is the business behind the generator

The support section lists what the riok team offers, and it is a services list rather than a troubleshooting page.

Enterprise support and training, architecture consultation, custom feature development and integration support, and performance optimization and code reviews. Questions go to GitHub Discussions, and paid work is arranged by email at the riok domain. Sponsoring through GitHub is offered as a route to priority support.

That tells you something about the project's shape. The library is Apache 2.0 licensed and free, the documentation site is maintained alongside it, and the commercial offering is help rather than a feature tier.

For a team adopting a source generator, that also means the answer to an unusual mapping requirement is a conversation with the maintainers rather than a support ticket against a product. The code of conduct and a security policy file sit at the root alongside the contributing guide, which the site links.

Editorial conclusion

Use Mapperly when you want mapping code that a person can read and a debugger can step into, rather than a mapper that resolves types at run time. Install the stable channel for anything you ship, because the support policy covers only the latest stable release, and treat the next channel as a test surface where breaking changes are expected between prereleases. Before you upgrade across a major version, read the breaking change list the project publishes per version. In a solution, keep the mapper partial and attribute-driven so regeneration stays automatic, and remember that the cost of the generator is build time rather than run time. If your team needs help beyond that, the maintainers sell consulting and training around the library.

Frequently asked questions

How do I use Riok.Mapperly?

Add the package with dotnet add package Riok.Mapperly, then declare a partial class with the Mapperly Mapper attribute and write partial mapping methods on it. The generator supplies the implementations, and you call them like any other method.

Is Mapperly open source?

Yes. It is licensed under Apache 2.0, with the licence file at the root of the repository and the project documentation published at mapperly.riok.app.

Which Mapperly release channel should I use?

The stable channel for production, where semantic versioning applies and breaking changes only arrive in major versions. The next channel carries preview releases with upcoming features, may contain breaking changes, and is not subject to semantic versioning.

Does Mapperly use reflection at run time?

No. It is a source generator, so mapping code is created at build time and the claim is minimal overhead at run time, with the additional benefit that the generated code is readable and can be verified.

How many Mapperly versions are supported?

Only the latest version released on the stable channel is fully supported. The project also says it strives to support all .NET versions currently supported by Microsoft, rather than publishing a fixed list of target frameworks.

Where are Mapperly breaking changes listed?

The documentation site publishes a list of breaking changes for each major version along with upgrade guides, under an upgrading category. That matters most on the next channel, where prereleases may break between versions.

Official sources

  1. License: Apache-2.0
  2. Project website
  3. README
  4. Releases
  5. riok/mapperly on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/riok-mapperly.svg)](https://hysenlabs.com/projects/riok-mapperly)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/riok-mapperly.svg)](https://hysenlabs.com/projects/riok-mapperly)

Was this useful?