feat(maven): introduce maven plugin

.github/workflows/ci.yml

@@ -77,6 +77,7 @@ jobs:
         with:
           distribution: temurin
           java-version: 17
+          cache: maven
 
       - name: Setup Gradle
         uses: gradle/actions/setup-gradle@48b5f213c81028ace310571dc5ec0fbbca0b2947 # v4.4.3

.gitignore

@@ -62,6 +62,7 @@ out
 .profile
 .rustup/
 target
+.flattened-pom.xml
 *.wasm
 /wasi-sdk*
 
@@ -111,6 +112,8 @@ node_modules/
 
 astro-docs/.netlify
 
+coverage
+
 # Angular Rspack Specific Options
 packages/angular-rspack/coverage
 packages/angular-rspack-compiler/coverage
@@ -119,6 +122,7 @@ packages/angular-rspack-compiler/coverage
 packages/angular-rspack/README.md
 packages/angular-rspack-compiler/README.md
 packages/dotnet/README.md
+packages/maven/README.md
 
 test-output
 test-results

.mvn/wrapper/maven-wrapper.properties

@@ -0,0 +1,3 @@
+wrapperVersion=3.3.4
+distributionType=only-script
+distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.9/apache-maven-3.9.9-bin.zip

astro-docs/project.json

@@ -7,7 +7,7 @@
       "continuous": true,
       "dependsOn": [
         {
-          "projects": ["devkit", "create-nx-workspace", "dotnet"],
+          "projects": ["devkit", "create-nx-workspace", "dotnet", "maven"],
           "target": "build"
         }
       ],
@@ -19,7 +19,7 @@
     "build": {
       "dependsOn": [
         {
-          "projects": ["devkit", "create-nx-workspace", "dotnet"],
+          "projects": ["devkit", "create-nx-workspace", "dotnet", "maven"],
           "target": "build"
         }
       ],

astro-docs/sidebar.mts

@@ -108,8 +108,22 @@ export const sidebar: StarlightUserConfig['sidebar'] = [
       {
         label: 'Java',
         collapsed: true,
-        // when we have maven this will change to not have gradle as the top docs for Java
-        items: getPluginItems('gradle', 'java'),
+        items: [
+          {
+            label: 'Introduction',
+            link: 'technologies/java/introduction',
+          },
+          {
+            label: 'Gradle',
+            collapsed: true,
+            items: getPluginItems('gradle', 'java'),
+          },
+          {
+            label: 'Maven',
+            collapsed: true,
+            items: getPluginItems('maven', 'java'),
+          },
+        ],
       },
       {
         label: '.NET',

astro-docs/src/content/docs/technologies/java/gradle/index.mdoc

@@ -0,0 +1,9 @@
+---
+title: Gradle
+sidebar:
+  hidden: true
+description: Using Gradle with Nx
+pagefind: false
+---
+
+{% index_page_cards path="technologies/java/gradle" /%}

astro-docs/src/content/docs/technologies/java/gradle/introduction.mdoc

@@ -0,0 +1,301 @@
+---
+title: Overview of the Nx Plugin for Gradle
+description: This plugin allows Gradle tasks to be run through Nx.
+sidebar:
+  label: 'Introduction'
+filter: 'type:References'
+---
+
+[Gradle](https://gradle.org/) is a fast, dependable, and adaptable open-source build automation tool with an elegant and extensible declarative build language. Gradle supports Android, Java, Kotlin Multiplatform, Groovy, Scala, Javascript, and C/C++.
+
+The Nx plugin for Gradle registers Gradle projects in your Nx workspace. It allows Gradle tasks to be run through Nx. Nx effortlessly makes your [CI faster](/docs/guides/nx-cloud/setup-ci).
+
+Nx adds the following features to your workspace:
+
+- [Cache task results](/docs/features/cache-task-results)
+- [Distribute task execution](/docs/features/ci-features/distribute-task-execution)
+- [Run only tasks affected by a PR](/docs/features/ci-features/affected)
+- [Interactively explore your workspace](/docs/features/explore-graph)
+
+{% aside type="note" title="Java Compatibility" %}
+This plugin requires Java 17 or newer. Using older Java versions is unsupported and may lead to issues. If you need support for an older version, please create an issue on [Github](https://github.com/nrwl/nx)!
+{% /aside %}
+
+## Setup @nx/gradle
+
+### Install Nx
+
+You can install Nx globally. Depending on your package manager, use one of the following commands:
+
+{% tabs syncKey="package-manager" %}
+{% tabitem label="npm" %}
+
+```shell {% frame="none" %}
+npm add --global nx@latest
+```
+
+{% /tabitem %}
+{% tabitem label="Homebrew (macOS, Linux)" %}
+
+```shell {% frame="none" %}
+brew install nx
+```
+
+{% /tabitem %}
+{% tabitem label="Chocolatey (Windows)" %}
+
+```shell {% frame="none" %}
+choco install nx
+```
+
+{% /tabitem %}
+{% tabitem label="apt (Ubuntu)" %}
+
+```shell {% frame="none" %}
+sudo add-apt-repository ppa:nrwl/nx
+sudo apt update
+sudo apt install nx
+```
+
+{% /tabitem %}
+{% /tabs %}
+
+### Add Nx to a Gradle Workspace
+
+In any Gradle workspace, run the following command to add Nx and the `@nx/gradle` plugin:
+
+```shell {% frame="none" %}
+nx init
+```
+
+Then, you can run Gradle tasks using Nx. For example:
+
+```shell {% frame="none" %}
+nx build <your gradle library>
+```
+
+## How @nx/gradle Infers Tasks
+
+The `@nx/gradle` plugin relies on a companion Gradle plugin, `dev.nx.gradle.project-graph`, to analyze your Gradle build structure. When using `nx add`, the Gradle plugin is added as a dependency to the root Gradle build file. In most cases, the generator will add the task definition to trigger the plugin but if it's missing, add the following configuration to your Gradle configuration:
+
+{% tabs syncKey="java-lang" %}
+{% tabitem label="build.gradle.kts" %}
+
+```kotlin
+// build.gradle.kts
+plugins {
+    id("dev.nx.gradle.project-graph") version("+")
+}
+
+allprojects {
+    apply {
+        plugin("dev.nx.gradle.project-graph")
+    }
+}
+```
+
+{% /tabitem %}
+{% tabitem label="build.gradle" %}
+
+```groovy
+// build.gradle
+plugins {
+    id 'dev.nx.gradle.project-graph' version '+'
+}
+
+allprojects {
+    apply plugin: 'dev.nx.gradle.project-graph'
+}
+```
+
+{% /tabitem %}
+{% /tabs %}
+
+The `dev.nx.gradle.project-graph` plugin introduces a task named `nxProjectGraph`. This task analyzes your Gradle projects and their tasks, outputting the structure as JSON. The `@nx/gradle` plugin then uses this JSON data to accurately build the Nx project graph. If Nx has any issue generate the project graph JSON, you can run the `nxProjectGraph` task manually:
+
+{% tabs syncKey="os" %}
+{% tabitem label="Mac OS/Linux" %}
+
+```shell {% frame="none" %}
+./gradlew nxProjectGraph
+```
+
+{% /tabitem %}
+{% tabitem label="Windows" %}
+
+```shell {% frame="none" %}
+.\gradlew.bat nxProjectGraph
+```
+
+{% /tabitem %}
+{% /tabs %}
+
+## View Inferred Tasks
+
+To view inferred tasks for a project, open the [project details view](/docs/features/explore-graph#explore-projects-in-your-workspace) in Nx Console or run `nx show project my-project` in the command line.
+
+## Setting Up @nx/gradle in a Nx Workspace
+
+In any Nx workspace, you can install `@nx/gradle` by running the following command:
+
+```shell {% frame="none" %}
+nx add @nx/gradle
+```
+
+## @nx/gradle Configuration
+
+The `@nx/gradle` is configured in the `plugins` array in `nx.json`.
+
+```json
+// nx.json
+{
+  "plugins": [
+    {
+      "plugin": "@nx/gradle",
+      "options": {
+        "testTargetName": "test",
+        "classesTargetName": "classes",
+        "buildTargetName": "build",
+        "ciTestTargetName": "test-ci",
+        "ciIntTestTargetName": "intTest-ci"
+      }
+    }
+  ]
+}
+```
+
+Once a Gradle configuration file has been identified, the targets are created with the name you specify under `testTargetName`, `classesTargetName` or `buildTargetName` in the `nx.json` `plugins` array. The default names for the inferred targets are `test`, `classes` and `build`.
+
+### Test Distribution
+
+Nx provides powerful features for distributing tasks in CI, including test splitting (also known as atomization) and optimized build targets. For Gradle projects, this is facilitated by the `@nx/gradle` plugin, allowing you to run your tests and builds more efficiently in your Continuous Integration (CI) environment.
+
+#### How to Set Up Test Distribution (Atomizer) in CI
+
+To enable test distribution for your Gradle projects in CI, follow these steps:
+
+1.  **Generate CI Workflow**: Run the `ci-workflow` generator to set up the necessary CI configurations. This generator creates a GitHub Actions workflow file that integrates with Nx's distributed task execution capabilities.
+
+    ```shell {% frame="none" %}
+    nx g @nx/gradle:ci-workflow
+    ```
+
+    This command will generate a workflow file (e.g., `.github/workflows/ci.yml`) tailored for your Nx workspace with Gradle projects.
+
+2.  **Configure `nx.json` for Atomizer**: Add or ensure the presence of `ciTestTargetName` or `ciIntTestTargetName` in the `@nx/gradle` plugin options within your `nx.json`.
+
+    ```json {% meta="{7,8}" %}
+    // nx.json
+    {
+      "plugins": [
+        {
+          "plugin": "@nx/gradle",
+          "options": {
+            "ciTestTargetName": "test-ci",
+            "ciIntTestTargetName": "intTest-ci"
+          }
+        }
+      ]
+    }
+    ```
+
+    Setting these options turns on the atomizer feature in CI. Nx will automatically split your testing tasks (unit and integration tests, respectively) by test class, allowing them to be run in a distributed fashion across your CI agents.
+
+3.  **Update CI Workflow Command**: In your generated CI workflow file, modify the command used to run affected tasks. Instead of using a generic `build` target, leverage the `build-ci` target provided by the `@nx/gradle` plugin:
+
+    ```shell {% frame="none" %}
+    # Before:
+    # ./nx affected --base=$NX_BASE --head=$NX_HEAD -t build
+
+    # After:
+    ./nx affected --base=$NX_BASE --head=$NX_HEAD -t build-ci
+    ```
+
+    This ensures that your CI pipeline utilizes the optimized `build-ci` target, which is designed to integrate seamlessly with Nx's test distribution and caching mechanisms.
+
+#### The `ci-workflow` Generator
+
+The `@nx/gradle:ci-workflow` generator is a utility that automates the setup of a CI workflow for your Nx workspace containing Gradle projects. It creates a `.github/workflows` file (or equivalent for other CI providers) that includes steps for checking out code, setting up Java and Gradle, restoring caches, and running affected Nx tasks. Its primary purpose is to streamline the integration of Nx's CI features, such as distributed task execution and caching, into your existing CI pipeline.
+
+#### The `build-ci` Target
+
+The `@nx/gradle` plugin can create a `build-ci` target that is specifically designed for use in CI environments. This target allows for a more optimized and consistent build process by ensuring that the `check` task is rewired to its CI counterpart (`check-ci`), which also implies that test tasks (`test` and `intTest`) are rewired to their atomized `test-ci` and `intTest-ci` counterparts respectively.
+
+##### What is it?
+
+The `build-ci` target is a synthetic Nx target that acts as a placeholder for your Gradle `build` task in a CI context. Instead of directly running the `build` task, the `build-ci` target ensures that the `check` task (a dependency of `build`) first executes its CI-optimized version (`check-ci`), which in turn uses the split/atomized test tasks (`test-ci`, `intTest-ci`). This allows for distributed execution of tests and efficient caching in CI.
+
+##### How to Enable?
+
+To enable the `build-ci` target, you need to configure `ciTestTargetName` or `ciIntTestTargetName` in the `@nx/gradle` plugin options in your `nx.json`.
+
+For example:
+
+```json
+// nx.json
+{
+  "plugins": [
+    {
+      "plugin": "@nx/gradle",
+      "options": {
+        "ciTestTargetName": "test-ci",
+        "ciBuildTargetName": "build-ci"
+      }
+    }
+  ]
+}
+```
+
+When `ciTestTargetName` (or `ciIntTestTargetName`) is set, the `build-ci` target is automatically created if the `build` task exists for a given Gradle project.
+
+##### Expected Behavior
+
+When you run `nx build-ci <your-gradle-project>`, Nx will:
+
+1.  Execute the `check-ci` task (if defined) instead of the standard `check` task.
+2.  The `check-ci` task will, in turn, trigger the atomized test tasks (`test-ci` and `intTest-ci`) if they are configured.
+3.  The `build-ci` target itself will use the `nx:noop` executor, meaning it doesn't execute a direct Gradle command, but rather relies on its dependencies (`check-ci`) to orchestrate the build process in a CI-friendly manner.
+4.  The `build-ci` target is cacheable.
+
+This setup ensures that your build process in CI leverages Nx's caching and distribution capabilities effectively.
+
+##### How to Turn it Off?
+
+To disable the `build-ci` target, simply remove the `ciBuildTargetName` option from the `@nx/gradle` plugin configuration in your `nx.json` file. If `ciTestTargetName` and `ciIntTestTargetName` are also removed, then the special CI targets for tests and check will also be turned off.
+
+### Continuous Tasks
+
+Gradle doesn't have a standard way to identify tasks which are [continuous](/docs/reference/project-configuration#continuous), like `bootRun` for serving a Spring Boot project. To ensure Nx handles these continuous tasks correctly, you can explicitly mark them as continuous.
+
+{% tabs %}
+{% tabitem label="nx.json" %}
+
+In the `nx.json`, you can specify the target default configuration like so:
+
+```json {% meta="{5}" %}
+// nx.json
+{
+  "targetDefaults": {
+    "someTask": {
+      "continuous": true
+    }
+  }
+}
+```
+
+{% /tabitem %}
+{% tabitem label="project.json" %}
+
+In a `project.json`, you can specify the target configuration like so:
+
+```json {% meta="{4}" %}
+// project.json
+{
+  "someTask": {
+    "continuous": true
+  }
+}
+```
+
+{% /tabitem %}
+{% /tabs %}