@nx/gradle

Gradle 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 Gradle plugin registers Gradle projects in your Nx workspace. It allows Gradle tasks to be run through Nx. Nx effortlessly makes your CI faster.

Nx adds the following features to your workspace:

• Cache task results
• Distribute task execution
• Run only tasks affected by a PR
• Interactively explore your workspace

Setup @nx/gradle

Install Nx

You can install Nx globally. Depending on your package manager, use one of the following commands:

Add Nx to a Gradle Workspace

In any Gradle workspace, run the following command to add Nx and the @nx/gradle plugin:

Then, you can run Gradle tasks using Nx. For example:

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:

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:

View Inferred Tasks

To view inferred tasks for a project, open the project details view 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:

@nx/gradle Configuration

The @nx/gradle is configured in the plugins array in nx.json.

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.

Splitting Tests

The @nx/gradle plugin will automatically split your testing tasks by test class if you provide a ciTestTargetName or ciIntTestTargetName. You can read more about the Atomizer feature here. Nx will create tasks with the names that you specify which can be used in CI to run the tests for each test class in a distributed fashion.

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:

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, like bootRun for serving a Spring Boot project. To ensure Nx handles these continuous tasks correctly, you can explicitly mark them as continuous.