Gradle Tutorial
This tutorial walks you through adding Nx to an existing Gradle project. You'll see how Nx enhances your Gradle workflow with caching, task orchestration, and better developer experience.
What you'll learn:
- How to integrate Nx with your existing Gradle build system
- How Nx's caching speeds up your Gradle builds locally and in CI
- How to visualize and understand project dependencies in your Gradle workspace
- How to run Gradle tasks more efficiently with Nx's task runner
- How to set up Nx Cloud for faster and self-healing CI
Ready to start?
This tutorial requires a GitHub account to demonstrate the full value of Nx - including task running, caching, and CI integration.
Step 1: Setup local env
Make sure that you have Gradle installed on your system. Consult Gradle's installation guide for instruction that are specific to your operating system.
To verify that Gradle was installed correctly, run this command:
❯
gradle --version
To streamline this tutorial, we'll install Nx globally on your system. You can use your preferred installation method below based on your OS:
Make sure Homebrew is installed, then install Nx globally with these commands:
❯
brew install nx
Step 2: Fork sample repository
This tutorial picks up where Spring framework's guide for Multi-Module Projects leaves off.
Fork the sample repository, and then clone it on your local machine:
❯
git clone https://github.com/<your-username>/gradle-tutorial.git
The Multi-Module Spring Tutorial left us with 2 projects:
- The main
applicationproject which contains the SpringDemoApplication - A
libraryproject which contains a Service used in theDemoApplication
You can see the above 2 projects by running ./gradlew projects
~/gradle-tutorial❯
./gradlew projects
1> Task :projects
2
3------------------------------------------------------------
4Root project 'gradle-tutorial'
5------------------------------------------------------------
6
7Root project 'gradle-tutorial'
8+--- Project ':application'
9\--- Project ':library'
10
11Add Nx
Nx is a build system with built in tooling and advanced CI capabilities. It helps you maintain and scale monorepos, both locally and on CI. We will explore the features of Nx in this tutorial by adding it to the Gradle workspace above.
To add Nx, run
~/gradle-tutorial❯
nx init
This command will download the latest version of Nx and help set up your repository to take advantage of it. Nx will also detect Gradle is used in the repo so it will propose adding the @nx/gradle plugin to integrate Gradle with Nx.
- You'll also be prompted to add Nx Cloud, select "yes"
- Select the plugin and continue with the setup.
Finally, commit and push all the changes to GitHub and proceed with finishing your Nx Cloud setup.
Finish Nx Cloud setup
Nx Cloud provides self-healing CI, remote caching and many other features. Learn more about Nx Cloud features.
Click the link printing in your terminal, or you can connect your existing workspace to Nx Cloud:
Finish Nx Cloud Setup ☁️Nx Cloud needs to be setup to complete the tutorial
Verify your setup
Please verify closely that you have the following setup:
- A new Nx workspace on your local machine
- A corresponding GitHub repository for the workspace
- You completed the full Nx Cloud onboarding, and you now have a Nx Cloud dashboard that is connected to your example repository on GitHub.
You should see your workspace in your Nx Cloud organization.
Explore Your Workspace
Like Gradle, Nx understands your workspace as a graph of projects. Nx uses this graph for many things which we will learn about in following sections. To visualize this graph in your browser, Run the following command and click the "Show all projects" button in the left sidebar.
You will recognize that the projects which are shown, are the same projects which Gradle shows. The @nx/gradle plugin reflects the graph of projects in Gradle into the Nx Project Graph. As projects are created, deleted, and change their dependencies, Nx will automatically recalculate the graph. Exploring this graph visually is vital to understanding how your code is structured and how Nx and Gradle behaves.
~/gradle-tutorial❯
nx graph
Running Tasks
Nx is a task runner built for monorepos. It can run a single task for a single project, a task for all projects, and even intelligently run a subset of tasks based on the changes you've made in your repository. Nx also has sophisticated computation caching to reuse the results of tasks. We will explore how Nx adds to the task running Gradle provides.
Before we start running tasks, let's explore the tasks available for the application project. The @nx/gradle plugin that we've installed reflects Gradle's tasks to Nx, which allows it to run any of the Gradle tasks defined for that project. You can view the available tasks either through Nx Console or from the terminal:
~/gradle-tutorial❯
nx show project application
The Nx command to run the build task for the application project is:
~/gradle-tutorial❯
nx run application:build
When Nx runs a Gradle task, it hands off the execution of that task to Gradle, so all task dependencies and configuration settings in the Gradle configuration are still respected.
By running the task via Nx, however, the task computation was cached for reuse. Now, running nx run application:build again, will complete almost instantly as the result from the previous execution will be used.
~/gradle-tutorial❯
nx run application:build
1
2 ✔ 1/1 dependent project tasks succeeded [1 read from cache]
3
4 Hint: you can run the command with --verbose to see the full dependent project outputs
5
6—————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————
7
8
9> nx run application:classes [existing outputs match the cache, left as is]
10
11> ./gradlew :application:classes
12
13> Task :library:compileJava UP-TO-DATE
14> Task :library:processResources NO-SOURCE
15> Task :library:classes UP-TO-DATE
16> Task :library:jar UP-TO-DATE
17> Task :application:compileJava UP-TO-DATE
18> Task :application:processResources UP-TO-DATE
19> Task :application:classes UP-TO-DATE
20
21BUILD SUCCESSFUL in 647ms
224 actionable tasks: 4 up-to-date
23
24> nx run application:build [existing outputs match the cache, left as is]
25
26> ./gradlew :application:build
27
28
29Deprecated Gradle features were used in this build, making it incompatible with Gradle 9.0.
30
31You can use '--warning-mode all' to show the individual deprecation warnings and determine if they come from your own scripts or plugins.
32
33For more on this, please refer to https://docs.gradle.org/8.5/userguide/command_line_interface.html#sec:command_line_warnings in the Gradle documentation.
34
35BUILD SUCCESSFUL in 768ms
369 actionable tasks: 1 executed, 8 up-to-date
37
38—————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————
39
40 NX Successfully ran target build for project application and 3 tasks it depends on (30ms)
41
42Nx read the output from the cache instead of running the command for 4 out of 4 tasks.
43Now that we've run one task, let's run all the build tasks in the repository with the Nx run-many command. This is similar to Gradle's ./gradlew build command.
~/gradle-tutorial❯
nx run-many -t build
1
2 ✔ nx run library:classes [existing outputs match the cache, left as is]
3 ✔ nx run library:build [existing outputs match the cache, left as is]
4 ✔ nx run application:classes [existing outputs match the cache, left as is]
5 ✔ nx run application:build [existing outputs match the cache, left as is]
6 ✔ nx run gradle-tutorial:classes (1s)
7 ✔ nx run gradle-tutorial:build (1s)
8
9—————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————
10
11 NX Successfully ran target build for 3 projects and 3 tasks they depend on (2s)
12
13Nx read the output from the cache instead of running the command for 4 out of 6 tasks.
14Again, because Nx cached the tasks when the application was built, most of the tasks here were near instant. The only ones which needed to be done is the root project's build. Running the command one more time, will be near instant as then all the tasks will be restored from the cache.
Remote Cache for Faster Development
With Nx Cloud connected, your task results are now cached remotely. This means that if another developer runs the same tasks, or if you run them in CI, the results will be retrieved from the remote cache instead of being re-executed.
Try running the build again after making a small change to see how Nx intelligently determines which tasks need to be re-run:
~/gradle-tutorial❯
nx run-many -t build
You'll notice that only the affected projects need to rebuild, while others are restored from cache.
Self-Healing CI with Nx Cloud
In this section, we'll explore how Nx Cloud can help your pull request get to green faster with self-healing CI.
You can copy the example GitHub Action workflow file and place it in the .github/workflows/ci.yml directory of your repository. This workflow will run the lint, test, and build tasks for all projects in your repository whenever a pull request is opened or updated.
The npx nx-cloud fix-ci command that is already included in your GitHub Actions workflow (github/workflows/ci.yml) is responsible for enabling self-healing CI and will automatically suggest fixes to your failing tasks.
1name: CI
2
3on:
4 push:
5 branches:
6 - main
7 pull_request:
8
9permissions:
10 actions: read
11 contents: read
12
13jobs:
14 main:
15 runs-on: ubuntu-latest
16 steps:
17 - uses: actions/checkout@v4
18 with:
19 filter: tree:0
20 fetch-depth: 0
21 - uses: actions/setup-node@v4
22 with:
23 node-version: 22
24 - name: Set up JDK 21 for x64
25 uses: actions/setup-java@v4
26 with:
27 java-version: '21'
28 distribution: 'temurin'
29 architecture: x64
30 - name: Setup Gradle
31 uses: gradle/actions/setup-gradle@v4
32 - run: npx nx run-many -t lint test build
33 - run: npx nx-cloud fix-ci
34 if: always()
35You will also need to install the Nx Console editor extension for VS Code, Cursor, or IntelliJ. For the complete AI setup guide, see our AI integration documentation.
Install Nx Console for VSCodeThe official VSCode extension for Nx.
Install Nx Console for JetBrainsAvailable for WebStorm, IntelliJ IDEA Ultimate and more!
Open a Pull Request
Start by making a new branch to work on.
~/gradle-tutorial❯
git checkout -b self-healing-ci
Now for demo purposes, we'll make a mistake in our DemoApplication class that will cause the build to fail.
1 @GetMapping("/")
2 public String home() {
3+ return myService.messages();
4- return myService.message();
5 }
6Commit the changes and open a new PR on GitHub.
~/gradle-tutorial❯
git add .
~/gradle-tutorial❯
git commit -m 'demo self-healing ci'
~/gradle-tutorial❯
git push origin self-healing-ci
Once pushed, CI will kick off, and we'll run into an error for the application:build task. When the build task fails, you'll see Nx Cloud begin to analyze the failure and suggest a fix. When a fix is proposed, Nx Console will show a notification for you to review the potential fix. From here you can reject or apply the fix. Applying the fix will commit back to your PR and re-trigger CI to run.
You can also see the fix link on the GitHub PR comment that Nx Cloud leaves.
From here you can manually apply or reject the fix:
For more information about how Nx can improve your CI pipeline, check out our CI guides
Summary
Now that you have added Nx to this sample Gradle repository, you have learned several ways that Nx can help your organization:
- Nx reflects the Gradle graph into the Nx graph
- Nx's dependency graph visualisation helps you understand your codebase
- Nx caches task results and reuses them when the same task is rerun later
- Nx Cloud provides self-healing CI and remote caching to speed up CI
- Nx intelligently determines which tasks are
affectedby code changes to reduce waste in CI
Next Steps
Connect with the rest of the Nx community with these resources:
- ⭐️ Star us on GitHub to show your support and stay updated on new releases!
- Join the Official Nx Discord Server to ask questions and find out the latest news about Nx.
- Follow Nx on Twitter to stay up to date with Nx news
- Read our Nx blog
- Subscribe to our Youtube channel for demos and Nx insights