In addition to the library and application plugins described in the following documentation, you can apply one of the following plugins to your project. For example, the minimal plugins can be used to reduce the number of tasks, for example if you don’t need Docker or GraalVM support:

Using the io.micronaut.application plugin:

is therefore equivalent to applying those plugins individually:

io.micronaut.minimal.application, io.micronaut.graalvm and io.micronaut.docker plugins (as well as the Eclipse annotation processing support plugin).

We recommend that you apply the io.micronaut.platform.catalog plugin to your settings.gradle(.kts) file. This plugin will automatically import the Micronaut version catalog, which provides a number of advantages:

Add the plugin to your settings.gradle(.kts) file:

The catalog is then exposed with the name mn and can be used in your build scripts, for example:

The minimum requirement is to set the Micronaut version to use. Since Micronaut 4, this is the version of the Micronaut Platform (in previous releases, releases were bound to the version of Micronaut Core).

The easiest is to set micronautVersion in gradle.properties. If you use a version catalog, you can also set the version of Micronaut directly in your libs.versions.toml file:

This version will be shared by all Micronaut modules of your project. Alternatively, you can set the version in your build.gradle(.kts):

Micronaut offers multiple options to override the default versions of its modules. For example, you may want to try a SNAPSHOT version of a module, or a release version which is not yet included in a new platform release. The easiest to do this is to make use of the Micronaut Platform version catalog.

For Kotlin, the Kotlin jvm and kapt plugins must be configured:

With the io.micronaut.library plugin applied a minimal build to get started writing a library for Micronaut that written in Java and is tested with JUnit 5 looks like:

With the io.micronaut.application plugin applied a minimal build to get started with a Micronaut server application that is written in Java and tested with JUnit 5 looks like:

The most simple Kotlin build using a build.gradle(.kts) file looks like:

Since version 3.0.0, the Micronaut plugins rely on the official GraalVM plugin to build native executables.

Those plugins make use of Gradle toolchains support, which means that the SDK which is used to build the native is decorrelated from the JVM which is used to launch Gradle itself. Said differently, you can run Gradle with OpenJDK, while still building native executables using the GraalVM SDK.

The Micronaut Gradle plugin will automatically configure the toolchains support for you, but there are a few things that you should be aware of:

If you have several GraalVM installations available, or that you want to disable the automatic toolchain recognition, we recommend that you do the following:

Alternatively you can pass those options from the command line:

You can build a native executable by running the following task:

And you can run it by calling the following task:

You can tweak the native executable options by configuring the graalvmNative extension as explained in the plugin documentation.

For example, you can add options to the main executable by doing:

A higher level concept of "runtimes" is included in the Micronaut Gradle plugin which essentially allows the plugin to decide which server runtime to include in the dependencies of the application when building the application. For example consider this minimal build:

Here the only dependency declared is on the logging framework to use however runtime is to netty resulting in an application that can be built and run.

If you wish to take the same and build or run it with a different runtime you can pass the micronaut.runtime property for the build. For example:

The above example run the application as a Google Cloud Function.

The available runtimes are:

The advantage of allowing your dependencies to be dictated by the runtime is that you can potentially take the same application and deploy it to any of the above runtimes without changes.

By default, the plugin doesn’t create a runnable fatjar when running ./gradlew assemble. There are a couple of options:

The io.micronaut.aot plugin is an extension to the io.micronaut.application plugin.

This will add an aot DSL block to the micronaut extension, which can be used to enable optimizations:

In addition, you can use the aotPlugins configuration to declare additional AOT modules to be used:

Because Micronaut AOT is an extensible optimization engine, not all optimizations are known beforehand by the plugin, which means that not all of them may be accessible via the DSL. For this reason, it is possible to provide a Micronaut AOT configuration file instead:

If you want to know about all possible optimizations, you can run the createAotSampleConfigurationFiles which will generate a couple of sample files:

The build/generated/aot/samples/jit/jit.properties will contain the optimizations which are relevant to an application running in the regular Java virtual machine, for example:

Another file, build/generated/aot/samples/native/native.properties will contain the same, but with the options which are relevant to an application compiled to a native executable:

For native executables, it is important to always have the graalvm.config.enabled option set to true, otherwise the AOT optimizations will not be loaded. The plugin takes care of setting this flag to true for you.

It is important to understand that Micronaut AOT works at build time. Therefore, some optimizations like conversion of YAML files to Java configuration will effectively disable the ability to change the configuration at runtime.

The plugin provides a couple of tasks aimed at running an optimized application. The first one, optimizedJar, will simply run the AOT compiler and produce an "optimized" jar. If you want to run the application with the resulting jar, you will need to call the optimizedRun task instead, which will create the jar and then start the application.

If you also have the distribution plugin applied, the optimized jar will be used to create optimized distributions, in which case you can call the optimizedDistZip task to create a distribution zip, the optimizedDistTar to create an optimized distribution tar file, or installOptimizedDist to install the optimized application to the build/install directory.

The plugin supports building an optimized fat jar. You will need to apply the shadow plugin to enable this feature:

Then you can generate the fat jar by calling: ./gradlew optimizedJitJarAll. The task will generate a fat jar in the build/libs directory, that you can run using:

java -jar build/libs/myapp-0.1-all-optimized.jar

The plugin creates a new native binary called optimized. The GraalVM plugin will then automatically create a couple of tasks for you:

It is also possible to build an optimized application and package it into a Docker image. For this, you need to call ./gradlew optimizedDockerBuild. It will produce a docker image that you can start using docker run.

Alternatively, you can call ./gradlew optimizedDockerPush to push the generated image to your docker registry.

All configuration options which apply to the standard docker image are also available to the optimized Docker images.

This task also produces a Docker image, but it will build a native image containing the optimized application within a container, in order to produce a Docker image which runs the optimized application natively.

The 2 tasks which are available for this are:

The easiest way to add test resources support is to apply the io.micronaut.test-resources plugin:

Adding this plugin will be sufficient for most use cases. This will let Gradle automatically start containers, for example, when a particular property is not present in your configuration and that you run tests (./gradlew test) or the application in development mode (./gradlew run or ./gradlew -t run).

For example, if the datasources.default.url configuration property is missing, and that your configuration contains:

Then a MySQL database will automatically be started and available for use in your tests: the url, username and password configuration properties will automatically be injected to your application.

Please refer to the Micronaut Test Resources documentation for a list of all supported modules and their configuration options.

In addition, the plugin will add a testResources extension to the micronaut configuration block, providing a number of options:

By default, native binaries are considered production code. This implies that the test resources client will not be included in the generated native binaries and therefore, by default, native applications will not make use of test resources.

In order to produce a native binary which is capable of using test resources, you must explicitly pass a system property to the build:

or, if you want to run the binary directly:

Note that you don’t need to do this for the nativeTest task, which is automatically configured to use test resources.

The io.micronaut.test-resources plugin works particularly well in single-module projects, or in multi-projects where test resources are not shared between modules. However, in some cases, you may want to reuse test containers for multiple projects of the same multi-project build, in order to save startup times for example.

For this purpose, the io.micronaut.test-resources plugin can be applied on a project independently of the application or library plugins.

For example, imagine a multi-project build which consists of :

If each project applies the io.micronaut.test-resources plugin independently, then each project will use its own test server, independently of the others.

However, you might want to run the consumer in one terminal, and the producer in another, and still want them to talk to the same Kafka cluster. For this you have a couple options:

The first solution comes with a major drawback: shared servers are shared by all projects in the multi-project build, but also between projects of the same build. However, the configuration of the server will depend on the first one started.

To avoid this problem it is recommended to declare a distinct project to handle test resources. Here, we’re going to add a project called shared-testresources which is going to be a test resources provider:

Then each consumer of test resources need to apply the io.micronaut.test-resources-consumer plugin instead:

Now Gradle will automatically start test resources when one of the project needs them, and reuse them in all consumer projects.

Test resources are handled by a service which is, by default, started at the beginning of a build, and stopped at the end.

For example, if you invoke:

./gradlew test

Then the test resources service will be started before tests are executed, then tests will share the resources provided by the service. Any test resource started during the test will be stopped when the build finishes.

In continuous mode, the test resources are shared between builds. For example, if you run:

./gradlew -t test (run test in continuous mode)

Then the test resources will be spawned during the first execution of tests. If you make any change to sources (production or test) and save the files, Gradle will rebuild the project and run the tests using the same test resources. This behavior can be extremely useful to save time since typically Docker containers would only be spawned once. If you interrupt the continuous build, the test resources will be stopped.

We have seen that running in continous mode allows keeping test resources alive as long as a continous build runs. However, what if you want to start the test resources service in the background, and keep it alive for multiple, independent builds (different invocations on the command line for example) ?

You can achieve this behavior by running the startTestResourcesService command:

./gradlew startTestResourcesService

This command must be the only command executed: it will start a test resources service in the background, which will be shared between builds. Therefore, it’s your responsibility to stop the service when you are done by running:

./gradlew stopTestResourcesService

Micronaut Test Resources provides integration with a lot of databases and services, and also supports a fully declarative way to spawn test containers. However, there are cases where you might need to implement your own test resources resolver.

The plugin makes it extremely straightforward: it declares an additional source set called testResources. You therefore write your test resources directly in src/testResources/java for example, and the test resource will be automatically made available.

For example, let’s write a test resource which provides the value of the greeting.message property.

First, let’s create the src/testResources/java/demo/GreetingTestResource.java file:

Then you need to declare the test resource in the service file descriptor:

Now the value of the greeting.message property will be available in your tests:

You can learn more about custom test resource resolvers in the Micronaut Test Resources documentation.

The io.micronaut.crac plugin is a standalone plugin which requires the following minimal configuration.

This will add a crac DSL block to the micronaut extension, which can be used to configure the image building:

You can generate a client by configuring the extension via the client { …​ } block:

The generated sources will be found by default in your $buildDir/generated/openapi/client directory, and automatically added to your main source set (so the classes are directly available for you to use).

Please refer to OpenApiClientSpec for the whole list of client configuration options.

You can generate a server by configuring the extension via the server { …​ } block:

The generated sources will be found by default in your $buildDir/generated/openapi/server directory, and automatically added to your main source set (so the classes are directly available for you to use).

Please refer to OpenApiServerSpec for the whole list of client configuration options.

The Micronaut OpenAPI plugin lets you override the default Micronaut OpenAPI version to use. To do this, set the version in the openapi extension:

In addition, it exposes a openApiGenerator configuration which can be used to declare additional dependencies to put on the generator classpath. This can be useful in case you want to implement your own generators, in which case you will also have to implement custom tasks which extend the AbstractOpenApiGenerator task type.

When the plugin detects you have a dependency with a group id corresponding to a known annotation processor for it, it adds the annotation processor automatically. The following annotation processors are currently supported by this feature.

In some circumstances, automatic dependencies – e.g. annotation processors listed above – can get in the way. This should be rare, but it is possible to suppress them, as follows. It has no default and using suppression shifts responsibility of adding the dependencies to the user.

When upgrading from the 2.x version of the plugins, you will need to change the configuration of the GraalVM native executable builds if you use them.

Typically, instead of configuring executable compilation using the task:

You now need to use the graalvmNative extension. This extension supports building multiple native executables, and the main one is named main (there is another one for tests, called test, which runs unit tests natively):

Similarly, to compile the native executable, you now need to run nativeCompile instead of nativeImage.

In addition, the official GraalVM plugin makes use of Gradle toolchains support, which can lead to surprising behavior if you are used to switching between local JDKs. If you are facing errors like this one:

then we recommend tweaking toolchain detection as described in this section of the documentation.

In any case, make sure to follow the configuration instructions.