> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nrwl/nx/llms.txt
> Use this file to discover all available pages before exploring further.

# @nx/gradle

> The Gradle plugin for Nx enables Java and Kotlin monorepo support by inferring tasks from your Gradle project structure.

The `@nx/gradle` plugin brings Nx's monorepo capabilities to Java and Kotlin projects managed by Gradle. It infers tasks directly from your Gradle project structure, maps Gradle tasks to Nx targets, and enables affected builds, task caching, and the Nx project graph for multi-project Gradle workspaces.

## Installation

```bash theme={null}
nx add @nx/gradle
```

Or install manually:

<CodeGroup>
  ```bash npm theme={null}
  npm install --save-dev @nx/gradle
  ```

  ```bash pnpm theme={null}
  pnpm add --save-dev @nx/gradle
  ```

  ```bash yarn theme={null}
  yarn add --dev @nx/gradle
  ```
</CodeGroup>

<Note>
  `@nx/gradle` requires Gradle to be installed and available on the `PATH`, or a `gradlew` wrapper script present in your workspace root.
</Note>

## What the plugin provides

<CardGroup cols={3}>
  <Card title="Inferred tasks" icon="bolt">
    Automatically discovers all Gradle subprojects and maps every Gradle task to an Nx target — no manual configuration needed.
  </Card>

  <Card title="Executors" icon="play">
    The `gradle` executor runs any Gradle task through the Gradle Tooling API or `gradlew`, with Nx caching support.
  </Card>

  <Card title="CI workflow" icon="check-circle">
    The `ci-workflow` generator scaffolds a CI pipeline configured to run Nx in a Gradle monorepo.
  </Card>
</CardGroup>

## Generators

### ci-workflow

Scaffold a CI workflow configuration that runs Nx commands for a Gradle-based workspace.

```bash theme={null}
nx generate @nx/gradle:ci-workflow
```

## Executors

### gradle

Run any Gradle task via the Gradle Tooling API or by invoking `gradlew`. Supports batch execution for running multiple tasks efficiently.

```json theme={null}
{
  "targets": {
    "build": {
      "executor": "@nx/gradle:gradle",
      "options": {
        "taskName": "build"
      }
    },
    "test": {
      "executor": "@nx/gradle:gradle",
      "options": {
        "taskName": "test"
      }
    }
  }
}
```

<Note>
  In practice, you rarely need to write this configuration manually. The `@nx/gradle` plugin infers these targets directly from your `build.gradle` or `build.gradle.kts` files.
</Note>

## Inferred tasks

This is the primary feature of `@nx/gradle`. Register the plugin in `nx.json` and Nx will automatically discover every Gradle subproject and every task it exposes.

```json theme={null}
{
  "plugins": [
    {
      "plugin": "@nx/gradle/plugin",
      "options": {
        "testTargetName": "test",
        "classesTargetName": "classes",
        "buildTargetName": "build"
      }
    }
  ]
}
```

Once configured, all Gradle tasks are available as Nx targets:

```bash theme={null}
# Build a Gradle subproject
nx build mylib

# Run tests
nx test mylib

# Run any Gradle task by name
nx run mylib:check
nx run mylib:jacocoTestReport
```

### How task inference works

<Steps>
  <Step title="Project discovery">
    Nx reads your `settings.gradle` or `settings.gradle.kts` to find all included subprojects. Each subproject becomes an Nx project.
  </Step>

  <Step title="Task mapping">
    For each subproject, Nx queries Gradle for available tasks and maps them to Nx targets. Standard tasks like `build`, `test`, `check`, and `clean` are mapped by default.
  </Step>

  <Step title="Dependency graph">
    Nx reads the `dependencies` block in each subproject's `build.gradle` to build the project dependency graph, enabling `nx affected` to work correctly.
  </Step>
</Steps>

## Configuration examples

### Multi-project Gradle workspace

A typical multi-project Gradle workspace structure:

```
my-workspace/
├── settings.gradle.kts
├── build.gradle.kts
├── nx.json
├── package.json
├── api/
│   ├── build.gradle.kts
│   └── src/
├── shared/
│   ├── build.gradle.kts
│   └── src/
└── client/
    ├── build.gradle.kts
    └── src/
```

### settings.gradle.kts

```kotlin theme={null}
rootProject.name = "my-workspace"

include("api")
include("shared")
include("client")
```

### api/build.gradle.kts

```kotlin theme={null}
plugins {
    kotlin("jvm") version "2.0.21"
    application
}

dependencies {
    implementation(project(":shared"))
    testImplementation(kotlin("test"))
}

application {
    mainClass.set("com.example.api.MainKt")
}

tasks.test {
    useJUnitPlatform()
}
```

### nx.json with caching configuration

```json theme={null}
{
  "plugins": [
    {
      "plugin": "@nx/gradle/plugin",
      "options": {
        "testTargetName": "test",
        "buildTargetName": "build"
      }
    }
  ],
  "targetDefaults": {
    "build": {
      "cache": true,
      "dependsOn": ["^build"],
      "inputs": ["production", "^production"]
    },
    "test": {
      "cache": true,
      "inputs": ["default", "^production", "{workspaceRoot}/gradle.properties"]
    }
  }
}
```

## Working with affected commands

Nx tracks which Gradle subprojects are affected by source changes, allowing you to skip tasks for unchanged projects:

```bash theme={null}
# Build only affected subprojects
nx affected -t build

# Test only affected subprojects
nx affected -t test

# View affected projects without running tasks
nx affected --print-affected
```

## Nx and Gradle side by side

You can run tasks using either the Nx CLI or Gradle directly. They are equivalent:

| Nx command            | Gradle equivalent        |
| --------------------- | ------------------------ |
| `nx build mylib`      | `./gradlew :mylib:build` |
| `nx test mylib`       | `./gradlew :mylib:test`  |
| `nx run mylib:check`  | `./gradlew :mylib:check` |
| `nx affected -t test` | *(no Gradle equivalent)* |

<Tip>
  Use the Nx CLI for all day-to-day tasks to benefit from caching, affected detection, and Nx Cloud distribution. Run `./gradlew` only when you need to pass Gradle-specific flags not exposed through Nx.
</Tip>