Overview of the Nx Plugin for Gradle

Gradle is a build automation tool for JVM-based projects.

The @nx/gradle plugin registers Gradle projects in the Nx graph so you can set up Gradle in Nx, run local tasks, configure task inference, and scale in CI.

You can use Gradle with Nx without the plugin and still get task caching, task orchestration, and the project graph.

Setup

Prerequisites

• Java 17 or newer

Install Nx

Install Nx with your preferred package manager:

npm

npm install --global nx@latest

You can use pnpm, yarn, or bun if you prefer as well.

Homebrew (macOS, Linux)

brew install nx

Chocolatey (Windows)

choco install nx

apt (Ubuntu)

sudo add-apt-repository ppa:nrwl/nx
sudo apt update
sudo apt install nx

Add Nx to a Gradle Workspace

From the root of your Gradle workspace, run:

nx init

Nx will add the @nx/gradle plugin and configure the Gradle companion plugin dev.nx.gradle.project-graph in your build files.

Gradle Companion Plugin

The dev.nx.gradle.project-graph plugin is added to your build.gradle or build.gradle.kts so Nx can read your Gradle project graph directly from source.

Verify the Setup

List the projects Nx inferred from Gradle:

nx show projects

Open the project details view for a specific project.

nx show project my-app

Local Development

Run Gradle tasks through Nx using inferred targets:

nx build my-gradle-lib
nx test my-gradle-lib

Nx maps these targets back to the Gradle tasks (for example build or test) and executes them using the Gradle wrapper. If a task should run in watch or server mode, mark it as continuous so Nx treats it correctly.

Configuration

How @nx/gradle Infers Tasks

Nx relies on the dev.nx.gradle.project-graph Gradle plugin to report your Gradle projects and tasks. The plugin adds an nxProjectGraph task that outputs JSON, which Nx uses to build the project graph. Nx also scans your Gradle build files to locate project roots and inputs so it can infer targets accurately.

The nx init workflow adds this plugin to your Gradle build files. If you ever need to add it manually, configure it in build.gradle or build.gradle.kts and apply it to all projects.

View Inferred Tasks

To view inferred tasks for a project, open the project details view in Nx Console or run:

nx show project my-app

Replace my-app with your project name.

@nx/gradle Configuration

Configure the plugin in the plugins array of nx.json:

nx.json

{
  "plugins": [
    {
      "plugin": "@nx/gradle",
      "options": {
        "testTargetName": "test",
        "ciTestTargetName": "test-ci",
        "targetNamePrefix": "gradle-",
        "gradleExecutableDirectory": "./gradle-projects"
      }
    }
  ]
}

How Options Work

Nx passes the plugin options to the Gradle nxProjectGraph task as Gradle properties. Any option that ends with TargetName overrides the inferred Nx target name for that Gradle task. Use this to avoid name clashes or to introduce CI-specific targets.

Options

Option	Type	Default	Description
testTargetName	string	test	Nx target name to map the Gradle test task.
ciTestTargetName	string	none	Enables CI test atomization and defines the base name for CI test targets.
targetNamePrefix	string	none	Prefix for all inferred Gradle targets (useful in polyglot workspaces).
gradleExecutableDirectory	string	none	Directory containing the Gradle wrapper to use.
<taskName>TargetName	string	none	Override for any Gradle task name (for example assembleTargetName).

Exclude or Include Specific Projects

Use include/exclude glob patterns to scope the plugin to specific projects:

nx.json

{
  "plugins": [
    {
      "plugin": "@nx/gradle",
      "include": ["apps/**/*"],
      "exclude": ["apps/legacy-app/**/*"],
      "options": { ... }
    }
  ]
}

Individual Gradle projects can also configure Nx-specific settings using the nx { } DSL in build.gradle or build.gradle.kts.

CI Considerations

Only run what changed in CI:

nx affected -t build test

Enable remote caching with Nx Cloud:

nx connect

See Set Up CI for provider-specific workflows. If you set ciTestTargetName, Nx will create CI variants that use atomized test targets.

Batch Mode

Batch mode runs multiple Gradle tasks in a single invocation. Enable it by setting NX_BATCH_MODE=true:

NX_BATCH_MODE=true nx run-many -t build test

If your Gradle builds require specific CI flags (for example --no-daemon or custom JVM args), add them to gradle.properties so Nx runs consistent settings locally and in CI.

What's Next

Gradle Tutorial Add Nx to an existing Gradle workspace step-by-step.

Java with Nx Overview of Java support across Gradle and Maven.

CI Workflow Generator Generate CI workflows that run affected tasks.

Gradle Generators Reference Full reference for @nx/gradle generators.

Gradle Executors Reference Full reference for @nx/gradle executors.