Skip to content

MapStruct dependency scope in a Maven project

MapStruct generates code at compile-time and it should not require any runtime dependencies:

How is MapStruct different from other bean mapping tools?

Unlike most other bean mapping tools, MapStruct doesn’t work at runtime but is a compile-time code generator.

Generating mapping code at build time has many advantages:

  • Excellent performance, as no reflection or byte code generation at runtime is needed; the generated code contains plain method invocations, just as if the mapper was hand-written
  • No runtime dependencies, making MapStruct a great solution for Android applications

Which dependency scope should be used in a Maven project? Should MapStruct be included as a provided dependency?




The org.mapstruct:mapstruct dependency contains the needed annotations to signal the org.mapstruct:mapstruct-processor what to do.

It also contains the Mappers factory that is used when using the default component model. Therefore, the scope of org.mapstruct:mapstruct depends on the component model that you are using:

Default component model

If you are using this component model then you need org.mapstruct:mapstruct during runtime if you are using Mappers or if you have dependencies between different mappers.

In theory you can use the default component model and instantiate your own mappers. However, dependencies between mappers are still going to use Mappers, unless you have instantiated your mapper in MyMapper.INSTANCE somehow already, then MapStruct will use MyMapper.INSTANCE to get the instance of the MyMapper. This would mean that you can still use the same scope as the other component models (see below for more information)

Other component model (spring, jsr330, cdi, etc.)

In this case you do not need org.mapstruct:mapstruct during runtime and you can use <optional>true</optional> with <scope>provided</scope>.

With Gradle this would be compileOnly dependency.

Note: Be careful when using Spring Boot and <scope>provided</scope> the Spring Boot maven plugin will still include the org.mapstruct:mapstruct dependency in the final provided jar. You’ll need to ignore it by configuring the Spring Boot Maven plugin.