Two Scala 3 LTS lines are supported, built from the same sources and published as separate artifacts. The compiler plugin API is not binary compatible across compiler releases, so the compiler version is part of the artifact name:

Selecting the wrong one does not fail gracefully: the 3.9.0 plugin loaded into the 3.3.8 compiler throws from inside the plugin phase and generates nothing. Match the artifact to the compiler exactly.

The repository version is independent of the Micronaut Core version. The initial development version is 1.0.0-SNAPSHOT.

The compiler plugin connects Scala compiler phases to Micronaut compile-time visitors. The Scala processing model supports bean definitions, injection, introspection, AOP, configuration properties, annotation metadata, Scala collections, Option, BeanRegistration, and Scala 3 enum lookup.

Scala 2 is not currently supported.

If you are new to Micronaut, Micronaut for Scala Developers explains dependency injection, configuration, introspections, serialization and AOP from the beginning, in Scala. For the wider framework documentation, see the Micronaut Framework user guide.

For Scala 3.9.0:

Use a released Micronaut Scala version in published applications. During development, the repository can be built against the Core SPI branch with IncludeGit or a local Core checkout:

Use the full compiler-version artifact ID for the compiler plugin, and the uncrossed artifact for the runtime support:

sbt builds should use CrossVersion.full so the complete Scala compiler version participates in the artifact coordinate. Mill builds should use the full-cross ::: dependency syntax. In both tools, select the integration version independently from the Scala compiler version.

Do not replace _3.9.0 with a binary Scala line suffix. Compiler plugin APIs can change between compiler releases, so a plugin built for one full compiler version must not be assumed to work with another. See the Scala compiler-plugin binary-compatibility guidance.

Most dependency injection frameworks decide at startup what to inject, by loading classes and reading their annotations with reflection. Micronaut decides at compile time. While your code is being compiled, the plugin reads your declarations and writes a BeanDefinition class beside each bean — a plain class holding the answers: what this bean’s dependencies are, how to construct it, what qualifies it.

Three things follow from that, and they are the reason the rest of this chapter looks the way it does:

Micronaut’s annotations are Java annotations, and Scala applies a Java annotation by rules of its own — a single value is not an array, and a positional argument does not go to value. Each difference is a compile error rather than a silent change in meaning, but the message names a type mismatch rather than the rule. Annotations lists them; it is worth reading before transcribing an example from Micronaut’s Java documentation.

A bean is an object Micronaut creates and supplies to whatever needs it. You declare one by annotating a class; you never write code that constructs it.

Start with something to inject. A trait describes what is needed, without saying which implementation provides it:

@Singleton on a class makes it a bean. Here two classes implement the same trait, so each is labelled with @Named to tell them apart:

A bean’s constructor parameters are its dependencies. Nothing marks them as injected — being a bean’s constructor is enough. Where more than one bean could satisfy a parameter, a qualifier says which, and @Named is the simplest one:

ApplicationContext.run().getBean(classOf[Vehicle]) returns a Vehicle with V8Engine supplied. Asking for a Vehicle without having declared V8Engine a bean is a compile error, not a startup failure.

Applications are configured from outside: a YAML file, environment variables, system properties. @ConfigurationProperties binds a class to a section of that configuration, and the bound object is itself a bean, so it can be injected anywhere:

With engine.manufacturer set to Ford and engine.cylinders to a list, this bean is created with those values. The Scala types are the point of the example:

Both come from micronaut-runtime-scala, which must be on the runtime classpath — see Quick Start. Remember that List and Map in Scala are not java.util.List and java.util.Map; both are supported, but a declaration means whichever one it names.

An introspection is compile-time reflection: for a type annotated @Introspected, the plugin generates a class that can read and write that type’s properties and call its constructor, without java.lang.reflect. It is what validation, data binding and serialization read.

BeanIntrospection.getIntrospection(classOf[Book]) then reports title and pages as properties and can instantiate the type from values. A case class needs nothing else: its constructor parameters are its properties, and the compiler-generated accessors are what the introspection reads.

An ordinary class works too. What becomes a property is a val or var, or a getter and setter pair — the same rules as anywhere else in Scala, since a val is a private field with a generated accessor.

Serialization is not part of the compiler plugin. It is Micronaut Serialization reading the introspection described above — which is why it works for Scala without anything Scala-specific. @Serdeable is @Introspected plus the instruction that the type may cross a serialization boundary:

An injected ObjectMapper then writes that as {"id":"A-1","quantity":3} and reads it back through the constructor the introspection describes. Because the introspection is generated at compile time, no reflective access to the type is needed at runtime, and the type works under GraalVM native image without configuration.

The dependency is io.micronaut.serde:micronaut-serde-jackson, added the same way as in any other language.

Scala’s own types need one thing more. Option, the Scala collections and a Scala 3 enum are none of them types Micronaut Serialization ships a serializer for — a Scala List is not a java.util.List, and a Scala 3 enum is not a java.lang.Enum — so micronaut-runtime-scala supplies those, and must be on the runtime classpath. Serialization is the chapter on what each of them becomes in a document.

Aspect-oriented programming (AOP) is how behaviour that is not specific to one method — timing, retry, caching, transactions, logging — is applied without writing it into every method. In Micronaut it is also compile-time: rather than generating a proxy at runtime, the plugin generates a subclass of your bean that overrides the advised methods, and the framework injects that subclass wherever the bean is asked for.

Around advice wraps a method call. It takes two declarations. First an annotation, marked @Around, that says "methods marked with this are advised":

Then an interceptor — itself a bean — bound to that annotation. It receives the call, does whatever it does, and calls proceed() to run the original method:

Applying it is just the annotation. It can go on a single method or on the class, in which case every method is advised:

Calling place runs the interceptor and returns ordered a book; calling quote does not run the interceptor at all.

Two Scala notes. The annotation extends java.lang.annotation.Annotation and overrides annotationType() because @InterceptorBean takes it as a classOf[…​] argument — see Annotations. And the advised class must be extensible, because the generated subclass extends it: a final class, or a final def on an advised method, is a compile error rather than a bean that quietly loses its advice.

Introduction advice is the other half of AOP, and the more surprising one. An around interceptor wraps a method that exists; an introduction interceptor provides methods that do not. You declare an abstract type with no implementation anywhere, and the interceptor supplies the behaviour — which is how Micronaut’s declarative HTTP clients and repository interfaces work.

The interceptor answers calls for the whole type, using the invocation context to decide what a given method should do:

The annotation is marked @Introduction and names the interceptor with @Type:

Then an abstract type carrying that annotation becomes a bean, despite having no implementation:

getBean(classOf[Greeter]).greet("Scala") returns greet(Scala) — the interceptor’s answer. A trait or an abstract class both work; an abstract class may also have concrete methods, which run normally, and dependencies of its own, which are injected.

Micronaut Data is worth meeting last, because a repository is introduction advice — the abstract type whose implementation you never write — applied to something you would otherwise write by hand.

An entity is a case class. Its parameters are its columns, and @Id marks the one the database generates:

A repository is a trait. Extending CrudRepository supplies the usual operations, and any further method is a query derived from its own name — read findByTitle as where title = ?:

There is no implementation of either anywhere, and none to write. At compile time the plugin generates the entity’s introspection, Data reads it to work out the table and columns, derives the SQL for every method, and generates the class that runs it. Injecting BookRepository gives you that class.

Three things from earlier chapters are load-bearing here, which is why this example is worth reading closely:

Both types in the example are Scala’s own — Long for the identifier, scala.List for the result — and both need a word of explanation, as does the one thing that has to be wired differently from a Java build. Micronaut Data is the chapter for that.

Micronaut can inject a constructor parameter, a field or a setter. Use the constructor.

The reason is stronger in Scala than in Java. A constructor parameter is in scope for the whole class body, so anything derived from a dependency can be a val computed once, and the class has no state that is briefly null:

Field injection cannot do this. @Inject var clock: Clock = null gives a mutable field that is null between construction and injection, so any val derived from it has to become a lazy val or a def, and the type says Clock while admitting null. There is no upside to recover: constructor parameters are injected without any annotation at all.

The other reason is testing. A bean whose dependencies are constructor parameters can be built directly with new in a unit test, with no container and no reflection.

@ConfigurationProperties binds a class to a section of configuration. Use a case class:

Four Scala things are doing work there, and each replaces something that would otherwise be an annotation or a convention:

One consequence of writing configuration this way is worth knowing: a class parameter has no field or accessor of its own to document, so its description goes on the class as a @param tag. That is where the generated configuration metadata takes it from — see Documentation in Generated Files.

Inject a trait, not a class. The bean asking for a dependency should name what it needs, and the container decides which implementation it gets:

This is ordinary good design, but it also unlocks things in Micronaut that a concrete class cannot do. Where several beans implement the trait, a collection parameter receives all of them — useful for anything plugin-shaped, where the set of implementations is meant to grow:

Where the dependency may not be there at all, an Option parameter is None rather than a failure, so a bean can adapt to an implementation being present without a null check:

And a trait is what introduction advice needs: an abstract type with no implementation is the input to @Introduction, which is how declarative clients work. See Micronaut for Scala Developers.

Where exactly one implementation could serve but you want to choose between several, qualify with @Named at the injection point. Prefer that over injecting the concrete class, which removes the choice permanently.

A bean has to be a class the plugin compiled, which leaves out the JDK, Java libraries and the Scala standard library. @Factory closes that gap: a method annotated with a scope produces a bean of whatever it returns.

java.time.Clock is now injectable anywhere, including into the ReportService above. This is also the right place for the construction logic of a type that needs assembling, so the beans that use it are not the ones building it.

@Singleton on an object works:

The instinct is understandable — Micronaut’s @Singleton and Scala’s object both mean "one of these" — but they are not the same thing, and the injection point shows it: the parameter’s type is HouseStyle.type, the singleton type of that one object, which nothing else can inhabit. There is no substituting a test double, no alternative implementation, and no qualifier to choose between. Worse, the object can also be reached by name from anywhere, so the dependency stops being visible in the constructor.

Prefer a class for anything with behaviour worth replacing, and keep object for what it is good at: constants and pure functions that nothing would ever want to inject differently.

Two Scala habits collide with how Micronaut applies AOP, and both are caught by the compiler rather than at runtime:

The -J—​add-modules=java.compiler argument is required: the plugin reaches Micronaut code that references javax.lang.model, and that module is not resolved by default in a JDK 9+ compiler process.

CrossVersion.full is required so that the full compiler version participates in the coordinate; the default binary suffix would resolve _3, which this project does not publish.

Mill’s full-cross dependency syntax is :::, which plays the same role as sbt’s CrossVersion.full.

The plugin does not define an option vocabulary of its own. Every option is placed into VisitorContext.getOptions(), which Micronaut itself and any TypeElementVisitor on the compilation classpath may read. The set is therefore open, and an unrecognised key is accepted rather than rejected — the same contract as javac’s `-A options.

-P:micronaut-scala:help prints this list.

Java lets a one-element array member be written without braces. Scala does not:

Wrap it, whether it holds one element or several:

In Java, a single unnamed argument goes to the member called value. Scala binds a positional argument by declaration order instead, which is the order the members appear in the annotation’s class file and is rarely the one you want. For jakarta.validation.constraints.Min, whose first declared member is message:

The habit that always works is to name every member, even when there is only one:

Scala has no repeatable annotations. Writing one twice is an error, so the container Java would generate has to be written out, with new on each entry:

Micronaut’s repeatable annotations each name their container in @Repeatable — @Requires uses @Requirements, @InterceptorBinding uses @InterceptorBindingDefinitions, @Property uses @PropertySource.

A Scala annotation extends scala.annotation.StaticAnnotation, and its members are constructor parameters. Give it @Retention(RetentionPolicy.RUNTIME) so Micronaut can read it, and @Target to say where it may be written:

An annotation used as a classOf[…​] argument — @InterceptorBean, @Type, @Introduction(interfaces = …​) — must also extend java.lang.annotation.Annotation and override annotationType(), because those members are declared as Class[? <: Annotation]. The Managed example above shows the full form.

StringBuilder in Scala is scala.collection.mutable.StringBuilder, a different type from java.lang.StringBuilder. An injection point or a bean method that means the Java one has to say so. The same applies to Seq, List and Map, which are Scala collections rather than java.util ones — both are supported, and micronaut-runtime-scala binds the Scala forms, but they are not interchangeable at a type level.

Nothing, in the compiler. Doc comments are kept by the Scala compiler without being asked, and the plugin reads them from there, so no flag, plugin option or build change is involved. What matters is how the comment is written.

Use a doc comment, not a line comment. Only /** … */ is a doc comment. A // comment above a declaration is invisible to the compiler by the time the plugin runs, however much it reads like documentation.

Document a property where its author can write it. This is the one rule that is specific to Scala, and it follows from how Scala declares properties. A class parameter — the usual way to write a @ConfigurationProperties class — has no field and no accessor of its own to attach a comment to, so its description goes on the class as a @param tag:

That is the same rule Java applies to a record, and it produces:

A member declared in the class body is documented where it is declared, as you would expect:

The first paragraphs are the description. Everything before the first block tag is used; from the first @param, @return, @throws or any other tag onward is not. So the sentence that should appear in generated documentation belongs at the top of the comment, not after a tag.

The plugin’s part is the same for all of them: it makes the documentation available to compile-time processing. What consumes it differs, and each brings its own dependency.

In each case the annotation still wins where you write one: an explicit @Schema(description = …) overrides what the comment says. Documentation is the default, not an override.

Only what the compiler is compiling. A doc comment is in a source file, and a dependency arrives as a class file with its comments long gone — so a type from another module or a library contributes no descriptions, in Scala exactly as in Java and Kotlin. Where that type’s description matters, write it on the member that exposes it, in the module being compiled.

With every member supplied, that writes as:

The rest of this chapter is what each of those members is doing.

A Some is written as the value itself, with no trace of the wrapper. A None is absence: the field is left out of the document rather than written as null, because that is what the type says.

Reading is where a Scala author has to make one decision. Give the member a default:

The default is what a document that omits the field falls back to. Without it the member is null — not None — which is a value the Scala type says cannot exist.

That is not a limitation of the plugin. Micronaut Serialization decides whether to ask a type for a default from a fixed list, and the list is java.util.Optional and its primitive variants; a Deserializer cannot add itself to it. Tracked upstream as micronaut-serialization#1416.

An explicit null in the document reads as None, with no default required. Only an absent field needs one.

List, Seq, Set, Vector, IndexedSeq and their mutable counterparts are all written as JSON arrays, and each is read back as the type the member declares rather than one shape for all of them. Map is written as a JSON object, keyed by the map’s own keys, the same way java.util.Map is.

Nothing has to name a concrete implementation. Write Seq[String] and a Seq comes back; write Vector[Int] and a Vector does.

Reading relies on the collection converters micronaut-runtime-scala registers, which are the same ones that bind configuration properties and injection points. A collection outside that set has to be reached through one that is in it.

An enum whose cases take no parameters is written as its case name and read back through the valueOf the compiler generates on it:

A name the enum does not have is rejected where it is read, rather than becoming a null the caller meets somewhere else.

The enum does not need @Serdeable of its own. An enum whose cases take parameters is a sum type rather than a set of names, has no valueOf, and is not covered — model it as a sealed hierarchy of @Serdeable case classes instead.

Everything else is ordinary Micronaut Serialization, and its own documentation applies unchanged: @JsonProperty and the other Jackson annotations it understands, naming strategies, views, @Serdeable.Serializable and @Serdeable.Deserializable for read-only or write-only types, and custom serializers of your own. Remember only that Scala applies a Java annotation by rules of its own — see Annotations.

Micronaut Data does its work in a TypeElementVisitor, and the compiler plugin discovers visitors from the compilation classpath — see Artifacts and Dependencies. So the processor is a compile-time dependency of the module holding the entities and repositories:

Then the ordinary runtime pieces — the JDBC implementation, a connection pool and a driver. For the in-memory database this chapter uses:

And micronaut-runtime-scala, which is what lets a repository method return a Scala collection — more on that below:

An entity is a case class. Its parameters are its columns, and @Id marks the one the database assigns:

The annotations are on the class parameters, because that is where a Scala property is declared. The plugin carries them to the property the introspection exposes, so Micronaut Data sees the same thing it would see on a Java record — the rule Idiomatic Scala gives for configuration applies here unchanged.

The identifier is Scala’s Long, which is the primitive. An entity that has not been saved yet has id of 0, not null — the same convention a Java entity with a long identifier follows, and what save returns has the identifier the database assigned.

A repository is a trait. Extending CrudRepository supplies the usual operations; any further method is a query derived from its own name — read findByTitle as where title = ? and countByPagesGreaterThan as select count(*) … where pages > ?:

There is no implementation of either type anywhere, and none to write. At compile time the plugin generates the entity’s introspection, Micronaut Data reads it to work out the table and columns, derives the SQL for every method including the inherited ones, and generates the class that runs it. Injecting BookRepository gives you that class.

It has to be a trait or an abstract class. A concrete class has a body of its own and cannot be introduced; a trait can have concrete methods too, which run as written.

@JdbcRepository(dialect = Dialect.H2) is written exactly as in Java — a Java annotation with a named enum argument — and CrudRepository[Book, Long] is the parameterized library supertype whose inherited methods Micronaut Data resolves against the entity.

findByTitle returns List[Book] — Scala’s List, not java.util.List. Micronaut Data asks at compile time whether a declared return type stands in for an Iterable so that it knows to generate a many-row query, and the plugin answers yes for a Scala collection. At runtime the rows arrive as a Java collection and micronaut-runtime-scala’s converters produce the declared one, so the caller gets `scala.List back. Write the Scala type and you get the Scala type.

Long return types are the primitive, as countByPagesGreaterThan shows.

A query that may find nothing is declared as java.util.Optional, as findFirstByTitle does — not Option. Micronaut Data recognises the single-result containers from a list of its own (Optional, the reactive types) and rejects anything else at compile time:

Convert at the call site with .toScala from scala.jdk.OptionConverters if an Option is wanted.

The repository binds to the default data source, so the ordinary Micronaut Data configuration applies. For an in-memory H2 database that creates its own schema:

That is all a test needs: start an ApplicationContext with those properties, inject the repository, and call it. Nothing about testing is Scala-specific.

micronaut-inject-scala_3.9.0 runs inside the Scala compiler and generates bean definitions. It bundles the Micronaut and ASM classes it compiles against, at their original package paths, because a Scala compiler plugin is loaded in an isolated classloader that cannot see the compile classpath.

That has two consequences worth knowing:

micronaut-runtime-scala is an ordinary small library holding the converters that let Micronaut bind Scala collections and scala.Option. Without it on the runtime classpath, a bean that injects a List[T], a Map[String, T] or an Option[T] will fail to bind at runtime even though it compiled.

It is not crossed with the compiler version, because it is not a compiler plugin.

TypeElementVisitor implementations are discovered with ServiceLoader from the compilation classpath. A visitor supplied by another Micronaut module — for example the validation processor — therefore has to be a compile-time dependency of the module being compiled, not a runtime one.

A visitor and its dependencies are loaded from that classpath, ahead of anything the compiler process itself was started with. The only classes a visitor shares with the plugin are the JDK’s, the compiler’s, and what the plugin jar bundles: Micronaut’s Element API and the annotations it ships. A library that both a visitor and the compiler’s own toolchain depend on — Gradle starts the compiler with scaladoc, and so with scaladoc’s Jackson and snakeyaml — is the version the module declares, never the toolchain’s.

The Scala version in the artifact name is the full compiler version, not the binary line. _3.9.0 is correct; _3 is not published. See Supported versions for why.

The project version is independent of the Micronaut Core version.

The artifact name carries the full Scala compiler version, as every compiler-side artifact here does — see Artifacts and Dependencies.

The harness compiles by invoking the Scala compiler directly, so it has to be told where the plugin and the compilation classpath are. Both are required, and the harness fails immediately if either is missing.

The properties are set in doFirst rather than at configuration time so that resolving the classpath does not happen during configuration.

AbstractScalaTypeElementSpec exposes the operations the specs in this repository are written against:

A visitor can be installed for the duration of one compilation to capture the VisitorContext, which is how the specs assert against elements the compiler produced rather than against elements they constructed.

Bean definitions are written into the class output directory by the compiler plugin, not through the compiler’s own output mechanism, so the build tool does not record them as products of the source that produced them.

The visible consequence is that deleting a bean’s source does not remove its bean definition. The generated $Foo$Definition.class and its META-INF/micronaut/io.micronaut.inject.BeanDefinitionReference/ marker both survive the rebuild, so a deleted bean is still a bean at runtime. The same applies to a definition left behind by a compilation that later failed.

Run a clean build after deleting or renaming a bean.

Listed because they look like gaps and are not:

The compilation succeeds and no $*$Definition classes appear.

The plugin is not being applied. A Scala compiler plugin has to be registered with the compiler itself, not added as a dependency — check that it is on the compiler plugin configuration (scalaCompilerPlugins, addCompilerPlugin, scalacPluginIvyDeps, or <compilerPlugins>) and not on implementation.

Run the compiler with -Xplugin-list to see which plugins actually loaded.

The plugin jar has been stripped of the classes it bundles, or replaced with one that never had them.

A Scala compiler plugin is loaded in a classloader built from its own -Xplugin argument, and that classloader cannot see the compile classpath. The published jar therefore carries the Micronaut and ASM classes it needs. Repacking it, or substituting a jar of only this project’s classes, removes exactly the classes the plugin loads first.

Declaring the dependencies separately does not help: build tools pass each resolved file as its own -Xplugin argument, so each gets its own classloader.

Something is passing more jars to -Xplugin than intended, usually transitive resolution of the compiler plugin configuration. The warnings are harmless — a jar without a plugin descriptor is skipped — but they indicate the configuration is resolving more than the one artifact it needs.

The java.compiler module is not resolved in the compiler process. Add:

to the Scala compiler arguments. See Build Tools for where it goes in each tool.

The artifact coordinate is using the binary Scala line rather than the full compiler version. This project publishes micronaut-inject-scala_3.9.0, not micronaut-inject-scala_3, because compiler plugin APIs can change between compiler releases.

In sbt use CrossVersion.full; in Mill use the ::: syntax; in Gradle and Maven write the full version into the artifact ID.

The code compiles, and injecting a List[T], Map[String, T] or Option[T] fails when the application starts.

micronaut-runtime-scala is missing from the runtime classpath. The converters live there rather than in the compiler plugin — see Artifacts and Dependencies.

A dependency-resolution rule is forcing the Scala 3 version onto Gradle’s own Zinc configuration. Zinc is built for Scala 2.13 and needs the 2.13 scala-library and scala-reflect; it is Gradle’s toolchain, not the project’s. Exempt the zinc configuration from any Scala pinning rule.

The source was deleted or renamed, and the application still resolves the old bean.

Bean definitions are not registered with the build tool as products of their source, so it does not clean them when the source goes. Run a clean build. See Limitations.

Options are passed through to VisitorContext.getOptions() and the set is open, so an unrecognised key is accepted rather than rejected. Check the spelling against Configuration Options.