////
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
////

=== Micronaut Integration

Grails supports using the Micronaut framework via the `grails-micronaut` plugin. The `grails-micronaut` plugin uses the https://micronaut-projects.github.io/micronaut-spring/latest/guide/#springBootStarter[Micronaut Spring Boot Starter] so that both the Micronaut Application Context & Grails Application Context exist side by side.

To enable Micronaut in your Grails application, two steps must be completed:

. Apply `grails-micronaut-bom` as `enforcedPlatform` (instead of `grails-bom`).
. Add the `grails-micronaut` library.

Here's an example build file:

[source,groovy]
.build.gradle
----
dependencies {
    // enforcedPlatform is required: it forces the selected Grails Micronaut BOM versions over the
    // versions declared by the Micronaut platform (for example Groovy 5 and javaparser-core),
    // preventing binary incompatibilities at runtime.
    implementation enforcedPlatform("org.apache.grails:grails-micronaut-bom:$grailsVersion")

    implementation 'org.apache.grails:grails-micronaut'
}
----

The `grails-micronaut-bom` layers Micronaut-specific dependency overrides on top of `grails-bom` and pins the `io.micronaut.platform:micronaut-platform` version it was built against. Applying it as `enforcedPlatform` makes all of its constraints strictly versioned so that no transitive dependency, including Micronaut's own platform, can override them. There is no need to set a `micronautPlatformVersion` Gradle property. See link:{versionsRef}Grails%20BOM%20Micronaut.html[Grails Micronaut BOM Dependencies] for the full list of managed versions.

==== Hibernate-Specific Micronaut BOMs

If your project targets a specific Hibernate version, use the corresponding Hibernate-specific Micronaut BOM instead of the generic `grails-micronaut-bom`:

* `org.apache.grails:grails-hibernate5-micronaut-bom` -- Micronaut + Hibernate 5 (the default).
* `org.apache.grails:grails-hibernate7-micronaut-bom` -- Micronaut + Hibernate 7. See link:{versionsRef}Grails%20BOM%20Hibernate7%20Micronaut.html[Grails Hibernate 7 Micronaut BOM Dependencies].

[source,groovy]
.build.gradle - Hibernate 5 with Micronaut
----
dependencies {
    implementation enforcedPlatform("org.apache.grails:grails-hibernate5-micronaut-bom:$grailsVersion")
    implementation 'org.apache.grails:grails-micronaut'
}
----

[source,groovy]
.build.gradle - Hibernate 7 with Micronaut
----
dependencies {
    implementation enforcedPlatform("org.apache.grails:grails-hibernate7-micronaut-bom:$grailsVersion")
    implementation 'org.apache.grails:grails-micronaut'
}
----

The generic `grails-micronaut-bom` remains available and currently tracks the Hibernate 5 default. If the framework changes its default Hibernate version in the future, `grails-micronaut-bom` will follow the new default while the Hibernate-specific BOMs remain pinned.

When the `grails-micronaut` plugin is present, the Grails Gradle plugin will automatically apply the required annotation processors to your project and validate that a Micronaut-compatible BOM (`grails-micronaut-bom`, `grails-hibernate5-micronaut-bom`, or `grails-hibernate7-micronaut-bom`) is applied as `enforcedPlatform`. The validation fails the build at configuration time with an actionable error if no such BOM is applied or it is applied as plain `platform(...)`.

==== Disabling the Micronaut Auto-Setup

The Micronaut auto-setup defaults to on. If a project deliberately deviates from the recommended setup, it can be disabled via the `grails` extension:

[source,groovy]
.build.gradle
----
grails {
    micronautAutoSetup = false // not recommended - also skips Micronaut BOM validation
}
----

WARNING: Disabling auto-setup is rarely appropriate. Without auto-setup, the Grails Gradle plugin will not validate that a Micronaut-compatible BOM is applied as `enforcedPlatform`. Without `enforcedPlatform`, Gradle's default conflict resolution allows the Micronaut platform to silently override the selected Grails Micronaut BOM versions of libraries such as Groovy and `javaparser-core`, leading to binary incompatibilities at runtime.

==== Generated Applications

Applications generated by https://forge.grails.org/[Grails Forge] with the Micronaut feature selected automatically use `enforcedPlatform("org.apache.grails:grails-micronaut-bom:$grailsVersion")` and require no further setup.
In Grails 8, Micronaut-enabled applications require JDK 25 or later; applications that do not use Micronaut continue to use the standard Java 21 baseline.
