Upgrade to Micronaut Framework 4

This post is a migration guide to Micronaut framework 4.0.

You can read about What’s new in Micronaut Framework 4.0 and its breaking changes to learn more about this recent release.

Gradle Applications

Version update

Set micronautVersion property in gradle.properties.

micronautVersion=4.0.0-M2

Update Gradle to 8

Micronaut framework 4 applications generated via the Micronaut CLI or Micronaut Launch use Gradle 8.1.1. Micronaut framework 3.x applications use Gradle 7.6. Upgrade your build from Gradle 7.x to 8.0.

Update Micronaut Gradle plugins to 4.x

Update Micronaut Gradle Plugin to 4.0.0-M2.

Replace:

plugins {
  id("io.micronaut.application") version "3.7.9"

With:

plugins {
  id("io.micronaut.application") version "4.0.0-M2"

Update Shadow plugin

Update Shadow Gradle Plugin to 8.1.1. Replace

Replace:

plugins {
  id("com.github.johnrengelman.shadow") version "7.1.2"

With:

plugins {
  id("com.github.johnrengelman.shadow") version "8.1.1"

Kotlin Gradle Plugins

If you write your Micronaut applications with Kotlin, you need to update your Gradle plugins.

kapt Gradle Plugin

Update kapt gradle plugin from 1.6.21 to 1.8.21.

Micronaut Framework 4.0 supports Kotlin Symbol Processing (KSP). We recommend you migrate from kapt to ksp.

All-open Gradle Plugin

Update Kotlin All-Open Gradle plugin from 1.6.21 to 1.8.21.

jvm Gradle plugin

Update Kotlin jvm Gradle plugin from 1.6.21 to 1.8.21.

Set source and target compatibility to Java 17

Micronaut Framework 4.0 sets the Java baseline to 17.

Update your Gradle build and set source and target compatibility.

java {
  sourceCompatibility = JavaVersion.toVersion("17")
  targetCompatibility = JavaVersion.toVersion("17")

Micronaut Framework BOM

The Micronaut Gradle plugin applies the Micronaut Bill of Materials (BOM). However, if you were applying the BOM directly to your build. You should use io.micronaut.platform:micronaut-platform.

The Micronaut Platform BOM exists since Micronaut framework 4, and corresponds to the Micronaut framework 3 BOM which was published at io.micronaut:micronaut-bom. In Micronaut framework 4, we provide both the Micronaut Platform BOM (io.micronaut.platform:micronaut-platform) and the Micronaut Core BOM (io.micronaut:micronaut-core-bom).

Maven Applications

Parent POM

Parent’s coordinate has changed.

Replace:

<parent>
  <groupId>io.micronaut</groupId>
  <artifactId>micronaut-parent</artifactId>

With:

<parent>
  <groupId>io.micronaut.platform</groupId>
  <artifactId>micronaut-parent</artifactId>

Version update

Set micronaut.version property in pom.xml.

  <parent>
    <groupId>io.micronaut.platform</groupId>
    <artifactId>micronaut-parent</artifactId>
    <version>4.0.0-M2</version>
  </parent>
  <properties>
   ...
    <micronaut.version>4.0.0-M2</micronaut.version>
  </properties>

Set source and target compatibility to 17

Micronaut Framework 4.0 sets the Java baseline to 17.

Set in pom.xml the following properties:

<properties>
...
    <jdk.version>17</jdk.version>
    <release.version>17</release.version>
...    
</properties>

Environment Deduction Disabled by Default

Environment deduction is disabled by default in Micronaut framework 4. You can enable it by setting the micronaut.env.deduction system property or the MICRONAUT_ENV_DEDUCTION environment variable to true or changing your mainclass.

public class Application {
    @ContextConfigurer
    public static class DeduceCloudEnvironmentConfigurer 
    implements ApplicationContextConfigurer {
        @Override
        public void configure(@NonNull ApplicationContextBuilder builder) {
        builder.deduceCloudEnvironment(true);
        }
    }

    public static void main(String[] args) {
        Micronaut.run(Application.class, args);
    }
}

YAML Configuration

Micronaut Framework 4.0 does not expose SnakeYAML as a transitive dependency.

If you use YAML for your application configuration, add the following dependency:

For Gradle:

dependencies {
    ...
    runtimeOnly("org.yaml:snakeyaml")
}

For Maven:

<dependency>
  <groupId>org.yaml</groupId>
  <artifactId>snakeyaml</artifactId>
  <scope>runtime</scope>
</dependency 

JSON Serialization

Micronaut Framework 4.0 does not expose Micronaut Jackson Databind as a transitive dependency.

Thus, you must choose which serialization implementation you want.

How to use Micronaut Jackson Databind

To use Micronaut Jackson Databind with Gradle, add the following dependency:

dependencies {
    ...
    implementation("io.micronaut:micronaut-jackson-databind")
}

Or to your Maven build:

<dependency>
  <groupId>io.micronaut</groupId>
  <artifactId>micronaut-jackson-databind</artifactId>
  <scope>compile</scope>
</dependency>

How to use Micronaut Serialization

To use Micronaut Serialization with Gradle, add the following dependency:

dependencies {
    ...
    annotationProcessor("io.micronaut.serde:micronaut-serde-processor")
    implementation("io.micronaut.serde:micronaut-serde-jackson")
}

Or to your Maven build:

    <dependency>
      <groupId>io.micronaut.serde</groupId>
      <artifactId>micronaut-serde-jackson</artifactId>
      <scope>compile</scope>
    </dependency>
</dependencies> 
...
..
.
<annotationProcessorPaths>
...
    <path>
        <groupId>io.micronaut.serde</groupId>
        <artifactId>micronaut-serde-processor</artifactId>
    </path>
</annotationProcessorPaths>

Micronaut Validation

Micronaut framework 4.0 moves Micronaut Validation to its own module. You need to replace the usage of the old coordinate io.micronaut:micronaut-validation.

To use Micronaut Validation with Gradle, add the following dependency:

dependencies {
    ...
    annotationProcessor("io.micronaut.validation:micronaut-validation-processor")
    implementation("io.micronaut.validation:micronaut-validation")
}

Or to your Maven build:

    <dependency>
      <groupId>io.micronaut.validation</groupId>
      <artifactId>micronaut-validation</artifactId>
      <scope>compile</scope>
    </dependency>
</dependencies> 
...
..
.
<annotationProcessorPaths>
...
    <path>
        <groupId>io.micronaut.validation</groupId>
        <artifactId>micronaut-validation-processor</artifactId>
    </path>
</annotationProcessorPaths>

Jakarta constraints

Replace the usage of javax.validation.constraints with jakarta.validation.constraints.

For example, replace:

import javax.validation.constraints.NotNull;
import javax.validation.constraints.Pattern;

with:

import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Pattern;

Websockets

Micronaut framework 4.0, io.micronaut:micronaut-http-server no longer exposes micronaut-websocket dependency transitively. To keep using [Micronaut WebSocket Support] add the following dependency to your application:

With Gradle:

implementation("io.micronaut:micronaut-websocket")

Or Maven

<dependency>
    <groupId>io.micronaut</groupId>
    <artifactId>micronaut-websocket</artifactId>
</dependency>

Jakarta Persistence Annotations

Replace the usage of javax.persistence with jakarta.persistence.

For example, replace:

import javax.persistence.GenerationType;
import javax.validation.constraints.NotNull;
import javax.persistence.Column;
import javax.persistence.Convert;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.Id;

with:

import jakarta.persistence.GenerationType;
import jakarta.validation.constraints.NotNull;
import jakarta.persistence.Column;
import jakarta.persistence.Convert;
import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.Id;

Retry Functionality

To use retry capabilities (@Retryable, @Recoverable), with Micronaut framework 4.0 you need to add the following dependency:

With Gradle:

implementation("io.micronaut:micronaut-retry")

With Maven:

<dependency>
    <groupId>io.micronaut</groupId>
    <artifactId>micronaut-retry</artifactId>
</dependency>

Micronaut Session

Micronaut framework 4.0 moves session capabilities to a new module, Micronaut Session. If you use session, replace the coordinates io.micronaut:micronaut-session with io.micronaut.session:micronaut-session.

Reactor Instrumentation moved to Reactor Module

Micronaut framework 4.0 moves Reactor instrumentation to Micronaut Reactor module. If you use Project Reactor, ensure you have the following dependency:

With Gradle:

implementation("io.micronaut.reactor:micronaut-reactor")

With Maven:

<dependency>
    <groupId>io.micronaut.validation</groupId>
    <artifactId>micronaut-validation</artifactId>
</dependency>