AutoMapper TS: object-to-object mapping for TypeScript

Mapping between shapes, declared once

AutoMapper TypeScript is the second iteration of the AutoMapper idea for TypeScript, and the repository is a monorepo of @automapper/core and official packages. The legacy package, @nartc/automapper, is archived and lives in this repository on a legacy branch, which the README explains in a Miscellaneous note.

The problem it solves is the one every project hits at some point: you have a domain entity with thirty fields, and an API response shape with twelve of them, and now you have a function that copies twelve fields by hand. Then the entity changes, and nothing tells you the copy function is out of date. Mapping declarations move that knowledge into configuration, where a change to the source type can be a type error rather than a silent omission.

The project is TypeScript, MIT licensed, and the documentation site is automapperts.netlify.app. The primary language in the repository listing is TypeScript, and the topics carry the automapper and mapper tags alongside the hacktoberfest ones, which is a hint about how the contributor base grew.

The release history shows the 9.x line landing in July 2026, with v9.0.1 and v9.0.2 published on the same day, 2026-07-16, and an earlier 8.8.1 from 2024-01-23 before that. The last push to the repository was on 2026-09-11 and it is not archived.

Choosing between the packages

The package table is the documentation for the architecture, because the choice of package is the choice of how the mapping is expressed.

@automapper/core is the core framework, and it works with plain interfaces and objects. @automapper/classes adds class instance support, and with it two sub-packages: @automapper/classes/mapped-types, which is the TypeScript type level counterpart, and @automapper/classes/transformer-plugin, which plugs the mapping into the class transformation step. @automapper/pojos is for plain JavaScript objects, for codebases that do not use classes at all.

Then the three integration packages, and these are the reason the monorepo exists. @automapper/mikro targets MikroORM, @automapper/sequelize targets Sequelize and @automapper/nestjs targets NestJS. The practical difference is where the mapping configuration lives: in the ORM integration, the mapping is declared next to the entity and the persistence layer, which is what you want if the shape difference is a persistence concern.

Most package rows in the table carry a README link, an npm badge and a bundlephobia badge for the minified and gzipped size. That is worth pausing on, because a mapping library is exactly the kind of dependency you do not want to add 60 kilobytes of. Publishing the size for each package is how the project keeps that honest.

The Miscellaneous section also names the package as @automapper/*, which is the newer scope, against the legacy @nartc/automapper.

The monorepo is an Nx workspace

The build and test tooling is Nx, and the root package.json shows the shape of it.

"test": "nx run-many --all --target=test --parallel",
"lint": "nx run-many --target=lint --parallel",
"typecheck": "nx run-many --target=typecheck --parallel"

Every task is a target executed across the workspace with Nx, and the same pattern is used for package and publish. There is a sync:check target for the Nx project graph, and a separate check:packages script that runs a Node script from tools/scripts to validate the package metadata. The packages/ directory holds the workspace members, pnpm-workspace.yaml declares the workspace, and pnpm is the package manager at version 8.15.9.

The release side is release-it, with the conventional-changelog plugin for the notes and a bumper plugin for the version, plus a beta channel that runs release-it with a major preRelease. The commit side is commitizen with cz-customizable and a git-cz script for the commit message. Contributors are managed with the all-contributors CLI, which is why the README has a contributors table.

The rest of the tree is a mature TypeScript workspace: nx.json and the .nx/ cache directory, tsconfig.base.json and tsconfig.json, vitest.shared.ts for the shared test configuration, a babel.config.json and @swc/core and @swc/cli for the transpilation, mise.toml for tool versions, version.json, migrations.json, and the .env-example for the environment the integration tests need.

The SonarCloud badges are a quality gate in disguise

The README opens with a row of SonarCloud badges, and the set of metrics chosen says something about how the project is run.

There is a lines of code badge, a maintainability rating, a quality gate status, a reliability rating and a security rating. The quality gate badge is the important one. A quality gate in SonarCloud is a threshold, and a project that publishes its gate status on the front page has made that threshold part of its definition of done, which usually means a pull request that fails the gate does not merge.

The five metrics together are a reasonable proxy set for a library: maintainability covers the complexity and duplication that a mapping library can easily accumulate, reliability covers the bugs Sonar finds in the code, and security covers the vulnerability classes. The lines of code badge is the odd one out, and it is published so that the size of the codebase is visible rather than implied.

The all-contributors badge, which counts twelve contributors, sits next to them, and the two together paint a picture of a small project with an unusually heavy emphasis on automated quality measurement. The GitHub Actions workflows in the .github/ directory are what would run those analyses alongside the Nx targets.

None of this is a substitute for reading the mapping documentation, but it does tell you that the project treats itself as a long-term library rather than a weekend experiment, which is what you want from something sitting between your domain model and your API.

Integration tests as a first-class package

The repository lists two packages under Others that are not published libraries, and they are the ones that tell you how the mapping is verified.

integration-test holds the integration tests of core and the official plugins, and nestjs-integration-test holds the integration tests for NestJS. Making them workspace packages rather than folders of test files inside each package is the right structure, because it means the same mapping configuration can be exercised against several adapters in one place, and a plugin that silently stops matching a core change fails a test rather than a user's application.

The test runner is Vitest, with vitest.shared.ts holding the shared configuration and the coverage provider being the v8 one. The developer dependencies show what the integration tests actually run against: NestJS 11 for the framework integration, MikroORM 6 for the MikroORM plugin, and the supertest types for HTTP level assertions.

The presence of supertest in the test dependencies tells you something specific. A mapping library is not only about copying fields, it is about how the mapped object behaves when it crosses a request boundary, and the framework integration tests are checking the mapped result as the application would emit it.

The other publishing detail worth noting is that the core and the plugin packages are published separately, with the bundlephobia badges in the table showing the cost of each one. You install the core and the single integration you need, not the whole set.

The 9.x line, the legacy branch, and what to check

Two version numbers appear in the repository and they mean different things, which is the first thing to sort out when you arrive.

The legacy package @nartc/automapper is archived and sits on a legacy branch inside this repository. The current packages are all @automapper/*, and the README describes them as a later iteration rather than a rename, so an article or a tutorial from the @nartc era will not match the current API even though the repository URL is the same.

The releases are v9.0.1 and v9.0.2, both on 2026-07-16, which is a two-patch release on the same day, so the 9.x line is young and the fixes are still landing. The 8.8.1 release from January 2024 is the last of the previous numbering.

The last push was on 2026-09-11, roughly two months after the newest tag, and the repository is not archived, so work continues in the tree ahead of the next release.

Two things are worth verifying before you commit to a version. First, that the package you need exists for the 9.x line, because the table lists every package with its own version badge and the sub-packages are versioned with the parent. Second, that your TypeScript and framework versions are supported, since the integration packages track their frameworks, and the NestJS integration is developed against NestJS 11 in the workspace's own development dependencies.

The documentation site is the place to check both, and the per-package READMEs in the repository are the versioned copies of it.

Editorial conclusion

Adopt AutoMapper TS if you are repeatedly writing hand-rolled functions that copy fields between a domain model and a DTO, and you want the mapping to be declared once and checked by the compiler. Do not adopt it for a handful of simple conversions, since the setup cost of a mapping configuration is not worth it there, and do not expect the API to be the same as the legacy @nartc/automapper, since that package is archived and this one is a later iteration. Before you start, pick the package that matches your stack, core for plain objects, classes for class instances, pojos for plain JavaScript objects, and the ORM-specific one if you want the mapping driven by your persistence layer.

Frequently asked questions

Official sources

1. License: MIT
2. nartc/mapper on GitHub
3. Project website
4. README
5. Releases