@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

nx add @nx/gradle

Or install manually:

npm

npm install --save-dev @nx/gradle

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

What the plugin provides

Inferred tasks

Automatically discovers all Gradle subprojects and maps every Gradle task to an Nx target — no manual configuration needed.

Executors

The gradle executor runs any Gradle task through the Gradle Tooling API or gradlew, with Nx caching support.

CI workflow

The ci-workflow generator scaffolds a CI pipeline configured to run Nx in a Gradle monorepo.

Generators

ci-workflow

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

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.

{
  "targets": {
    "build": {
      "executor": "@nx/gradle:gradle",
      "options": {
        "taskName": "build"
      }
    },
    "test": {
      "executor": "@nx/gradle:gradle",
      "options": {
        "taskName": "test"
      }
    }
  }
}

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.

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.

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

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

# 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

1. Project discovery

   Nx reads your settings.gradle or settings.gradle.kts to find all included subprojects. Each subproject becomes an Nx project.

2. 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.

3. 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.

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

rootProject.name = "my-workspace"

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

api/build.gradle.kts

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

{
  "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:

# 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)

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.