What is the Nx Gradle plugin, and what does it own versus Gradle?

The Nx Gradle plugin is an orchestration layer that sits on top of Gradle. It does not replace Gradle. It reads your Gradle build to discover projects and their tasks, adds them to the Nx project graph, and runs them by calling the Gradle wrapper. Gradle still does the actual Java work.

The boundary matters because each tool is authoritative for different questions:

Concern Owned by Gradle Owned by Nx
Compilation and toolchains Yes: JDK selection, javac, Kotlin No
Dependency resolution Yes: Maven coordinates, version catalogs No
Spring Boot packaging Yes: executable jars, layered images No
Repository-wide project graph Only for Gradle projects Yes: spans Gradle and Node projects
Cross-language task ordering No Yes
Affected-project detection No Yes: maps Git changes onto the graph
Caching Gradle build cache (task outputs) Nx computation cache (target outputs)
                 +------------------------------------+
                 |                 Nx                 |
                 |  project graph | affected | cache  |
                 +-----------------+------------------+
                                   |
                 +-----------------+------------------+
                 v                                    v
        +------------------+               +-------------------+
        |  ./gradlew       |               |  Node tooling     |
        |  Spring Boot     |               |  (npm/pnpm, tsc)  |
        |  services, libs  |               |  web apps, SDKs   |
        +------------------+               +-------------------+
                 \                                    /
                  `------ shared Nx project graph ---'

Most confusion comes from blurring this boundary. If a Spring Boot service resolves the wrong library version, fix it in Gradle. If a TypeScript client rebuilds before the API contract it depends on, fix it in Nx. Do not try to fix one tool's problem from inside the other. The two caches are also separate layers, so you need to understand both before you tune either one.

+------------------------------------------------------------------------+
|   Nx: project graph | task ordering | affected | computation cache     |
|                                                                        |
|  +------------------------------------------------------------------+  |
|  |         shared Nx project graph (spans Gradle and Node)          |  |
|  |  [svc-orders] --> [lib-domain]        [web-app] --> [api-sdk]    |  |
|  |       ^                                   |                      |  |
|  |       +------- cross-language dep --------+                      |  |
|  +------------------------------------------------------------------+  |
+-----------------+------------------------------------+-----------------+
                  |                                    |
                  | ./gradlew <task>                   | npm/pnpm <script>
                  v                                    v
    +----------------------------+       +----------------------------+
    | Gradle (via wrapper)       |       | Node tooling               |
    | compile, toolchains (JDK)  |       | npm / pnpm, tsc            |
    | dependency resolution      |       | TS compile, bundling       |
    | Spring Boot jars/images    |       | web apps, TS SDKs          |
    | Gradle build cache         |       |                            |
    +----------------------------+       +----------------------------+

  Gradle answers 'how to build Java'; Nx answers 'what to run, in what order'

Nx sits above the Gradle wrapper and Node tooling, owning the shared project graph, task ordering, affected detection and its computation cache, while Gradle keeps compilation, dependency resolution, toolchains and Spring Boot packaging.

Who should use Nx with Gradle, and when should you avoid it?

The payoff comes when Spring Boot services share a repository with Node frontends, TypeScript SDKs or scripting tools. In that setup you get one project graph, one affected computation and one cache across every language. A change to a Java DTO can mark the generated client and the React app as affected in the same pass. Gradle cannot see those Node projects, so it cannot make that connection.

The costs are real:

  • Two mental models. Engineers must know which tool owns which behaviour. When a build fails, there are two places to look.
  • Configuration time. Nx builds its graph by running Gradle's configuration phase. On a cold CI runner with no warm daemon, that time is added before any task starts.
  • A Node.js toolchain in the JVM build path. This means more dependencies for supply-chain review and more runner image maintenance.
  • Version churn. The Gradle integration changes faster than Gradle does. Pin its version and upgrade it on purpose.
  • Bypassed locally. JVM engineers working in the IDE will often run Gradle directly. Nx's local cache then only helps in CI.

If the repository is JVM-only, you will rarely gain enough to justify the extra layer.

Approach Cross-language graph Affected detection Caching Migration effort
Gradle alone (build cache, composite builds) No Not built in; needs custom scripts Strong for JVM tasks Lowest
Nx with hand-written project.json run-commands Yes, but maintained by hand Yes, only as accurate as the declared dependencies Nx cache, with inputs declared manually Moderate; drifts over time
Nx Gradle plugin Yes, inferred from Gradle Yes Nx cache plus Gradle build cache Moderate
Other polyglot build systems Yes Yes Strong, hermetic Highest; requires rewriting build definitions

How do you add the Nx Gradle plugin to an existing Spring Boot monorepo?

Start with a layout where the Gradle build has one clear root. A typical polyglot repo might look like this:

  • settings.gradle.kts and the Gradle wrapper at the repository root
  • services/orders, services/billing, services/inventory: Spring Boot applications, each with its own build.gradle.kts
  • libs/shared-domain: a plain Java library consumed by the services
  • apps/web and apps/admin: Node projects with their own package.json

The location of the settings file matters because Nx learns about Gradle projects by asking Gradle. The plugin finds Gradle builds through their settings and build files, then reads the project structure Gradle reports. Anything not included in that settings file does not exist from Gradle's point of view, so Nx will not see it as a Gradle project. If your services live under a nested directory with their own settings file, that directory becomes a separate build, and Nx treats it that way.

Run nx add @nx/gradle from the workspace root. It installs the package and registers a plugin entry in nx.json. That entry lists the plugin and an options object that maps inferred task names, such as build and test. Option names have changed between releases, so open the generated nx.json in your own workspace and read what was actually written. Don't copy keys from older examples.

You don't need a project.json per service. Nx infers projects, targets, and inter-project dependencies from the Gradle build itself.

If your build relies on buildSrc, convention plugins, composite builds (includeBuild), or custom task wiring, start small. Include two or three services first, check what Nx infers, and widen the scope once the graph matches your expectations.

// settings.gradle.kts at the repository root (next to gradlew).
// Nx asks Gradle for its project structure, so only projects included
// here become Gradle projects in the Nx graph.

rootProject.name = "polyglot-monorepo"

// Convention plugins from a separate build. Composite builds like this
// are a good reason to start with a small subset of services.
pluginManagement {
    includeBuild("build-logic")
}

// Shared Java library consumed by the services.
include("libs:shared-domain")

// Start small: include two services, run `nx add @nx/gradle`, then check
// what Nx inferred (for example with `nx show projects` and `nx graph`).
include("services:orders")
include("services:billing")

// Add this once the inferred graph matches what you expect.
// include("services:inventory")

// apps/web and apps/admin are not listed here. They are Node projects
// that Nx discovers from their package.json files, not through Gradle.

A root settings.gradle.kts that defines which Spring Boot services and libraries Nx can infer as Gradle projects, starting with a subset of services before adding the rest.

How does Nx build its project graph from Gradle, and how do you verify it?

Rather than parsing build.gradle.kts files as text, the plugin asks Gradle itself to evaluate the build and report what it finds: which projects exist, which tasks each one exposes, and which projects depend on which. Nx turns that report into projects, targets, and graph edges. Because Gradle does the evaluation, logic in convention plugins and buildSrc is applied the same way it is during a normal build. The trade-off is that graph computation costs a Gradle configuration pass. Nx caches the result and recomputes it when build files change.

Verifying the graph

Start with nx graph, which opens an interactive view of every project and edge. Then inspect a single service with nx show project <name>. It lists the targets Nx inferred, such as build, test, and bootJar, and which Gradle task each one runs. If a target you rely on is missing, fix that before you wire up CI.

To test an edge, use a service whose build file declares implementation(project(":shared")). In nx graph, that service should have an arrow pointing to shared. If there is no arrow, the dependency did not reach Nx. Common causes are a project excluded by the plugin configuration or a dependency added through custom resolution logic instead of a project dependency.

What the graph cannot see

Nx only knows about coupling that Gradle declares. Spring services are often coupled in ways Gradle never sees:

  • Runtime configuration: properties that one service reads and another sets.
  • Shared resource files: files copied in by a script.
  • HTTP contracts: APIs that one service calls on another.

None of these produce edges, so a change to one of them will not mark the dependent service as affected. Section 7 covers how to declare them explicitly.

# services/orders-service/build.gradle.kts declares a Gradle project dependency:
#
#   plugins {
#       java
#       id("org.springframework.boot")   // version managed in settings.gradle.kts
#   }
#   dependencies {
#       implementation(project(":shared"))   // should become an Nx edge
#       implementation("org.springframework.boot:spring-boot-starter-web")
#   }

# 1. Open the interactive graph of every project and edge.
npx nx graph

# 2. Narrow the view to one service and its direct neighbours.
npx nx graph --focus=orders-service

# 3. List the targets Nx inferred (build, test, bootJar, ...) and the Gradle task each runs.
npx nx show project orders-service

# 4. Check the edge from a script, e.g. as a CI sanity check.
npx nx graph --file=graph.json
jq -e '.graph.dependencies["orders-service"] | map(.target) | index("shared")' graph.json \
  && echo "edge orders-service -> shared present" \
  || echo "missing edge: check plugin exclusions and the project(\":shared\") declaration"

# Note: coupling through shared application properties, copied resource files
# or HTTP calls between services will NOT appear in graph.json unless declared.

Verifies that a Gradle implementation(project(":shared")) dependency shows up as an orders-service -> shared edge in the Nx project graph, both visually and from a script.

How do you run Spring Boot builds and tests through Nx and limit CI to affected projects?

With the graph in place, Gradle tasks become Nx targets. For a single service, nx build orders-service or nx test orders-service runs the corresponding Gradle task. To cover every JVM project at once, use nx run-many -t build test. Nx orders the work by the project graph, so a shared library builds before the services that consume it. The exact target names depend on how the plugin infers them from your Gradle tasks, so check nx show project orders-service if a name doesn't match.

Nx doesn't replace Gradle here. It calls the Gradle wrapper in your repository, so the wrapper-pinned Gradle version, configured JDK toolchains, the Spring Boot Gradle plugin (bootJar, layered jars) and any convention plugins in buildSrc all behave as they do when you run ./gradlew yourself. Nx only decides which tasks run and in what order.

The bigger gain comes from nx affected -t build test. Nx compares the current commit with a base ref and selects only the touched projects and the projects that depend on them.

  • Shared library change: If you edit shared-domain, every service that depends on it is marked affected and rebuilt. That is the correct result, because those services compile against the changed code.
  • Frontend-only change: If you edit the React app, no Gradle project is selected, and the JVM builds and tests don't run.

That second case is where the time savings come from. In a mixed repository, a frontend change no longer waits on Gradle configuration, compilation and Spring context tests that it could not have broken.

#!/usr/bin/env bash
set -euo pipefail

# Single service: Nx runs the inferred Gradle tasks through ./gradlew,
# so the wrapper-pinned Gradle version and JDK toolchain apply unchanged.
npx nx build orders-service
npx nx test orders-service

# If a target name doesn't match, list what the plugin inferred.
npx nx show project orders-service

# Many services: Nx orders tasks by the project graph,
# so shared-domain builds before the services that consume it.
npx nx run-many -t build test

# CI: only touched projects and their dependents.
# Compare the PR head against the main branch.
BASE_REF=origin/main

# Preview the selection before running anything.
npx nx show projects --affected --base="$BASE_REF" --head=HEAD

# Scenario A: change in shared-domain
#   -> shared-domain plus every service that depends on it is listed.
# Scenario B: change only in the React app
#   -> only the frontend project is listed. No Gradle task runs.

npx nx affected -t build test --base="$BASE_REF" --head=HEAD

Running Spring Boot Gradle targets through Nx, first for one service and then for all of them, and then limiting CI to affected projects so a frontend-only change skips the JVM builds.

How should Nx caching and Gradle's build cache work together?

To restore a Gradle task safely, Nx needs two things. The first is a complete set of inputs: sources, build scripts, version catalogs, gradle.properties, the wrapper version and any environment variables that change output. The second is declared outputs, usually the project's build/ directories. Gradle already tracks this per task through up-to-date checks and, if enabled, its build cache. When both layers are on, both store and restore the same artifacts. That doubles storage. It also creates two places where a missing input can go unnoticed.

The two failure modes are not equally costly. A miss costs a few minutes of rebuild. A wrong hit can restore a bootJar built from an older dependency or profile setting, and that stale jar passes CI and gets deployed. Treat any unexplained hit as a bug.

Artifact Authoritative layer Why
Compile Gradle Task-level fingerprinting and incremental compilation are finer-grained than a project hash
Test Gradle Test inputs include the runtime classpath, which Gradle already tracks
bootJar Gradle, Nx caching off Packaging is cheap; a stale jar is expensive
Generated artifacts (e.g. OpenAPI clients) Nx Non-Gradle projects consume them, and Nx sees both sides

Enable one layer first. Confirm that its hits are correct: change an input and check that the task reruns. Then widen.

Illustrative estimate. These inputs are assumptions, not measurements: 40 PRs a day, Gradle work of 12 minutes per PR, and 60% of PRs touching only frontend code. Skipping Gradle on those PRs saves about 40 × 0.6 × 12 ≈ 290 CI minutes a day, before counting any cache hits.

How do you declare cross-language dependencies such as an OpenAPI contract?

That saving only holds if Nx knows exactly where frontend and backend meet. In most polyglot repos, that point is the API contract. Suppose orders-service generates openapi.json from its controllers, and the web app generates a TypeScript client from that file. Without an explicit declaration, the coupling exists only as a relative path in a script. Nx then has three problems: it can run web:build before the spec exists, it can restore a cached client built from an old contract, and it won't list web as affected when only a controller changes.

To fix this, make the edge explicit in the frontend's project.json. Three settings do the work:

  • dependsOn on the client-generation target. Point it at orders-service and the Gradle task that writes the spec, which the Nx Gradle plugin exposes as a target. This ensures the spec is generated before the client.
  • inputs on the client-generation target. Include the spec file itself, using a {workspaceRoot}-relative path into the service's build directory. The cache key then changes whenever the contract changes. It does not change on edits to service internals that leave the spec untouched.
  • outputs on the service's spec-generation target. Declare the spec as an output so a cache hit restores the file instead of skipping it.

Because dependsOn names another project, Nx also adds a dependency on orders-service to the project graph. Open nx graph and confirm there is an edge from web to orders-service. Then edit a controller and check that nx show projects --affected includes web. If it doesn't, the dependency isn't declared correctly.

CI setup and troubleshooting checklist

CI runners need three toolchains: Node for Nx itself, a JDK matching your services' toolchain, and the committed Gradle wrapper. Always invoke ./gradlew rather than a system Gradle so the version Nx infers against matches the version developers use. Fetch enough git history for Nx to resolve the base commit. A shallow clone of depth 1 makes affected comparisons fail or fall back to treating everything as changed, so fetch full history or at least back to the merge base.

On ephemeral runners the Gradle daemon starts cold on every job, so it gives you no warm JVM. Your speed comes from restoring the Gradle dependency cache and wrapper distribution. Key that cache on the wrapper properties and build scripts so it is invalidated when dependencies change.

Context Canonical entry point Why
CI nx affected -t build test Limits work to changed projects and applies Nx caching
Local nx run <project>:<target> or ./gradlew directly Fast iteration; Gradle-only work stays familiar

Record this choice in your contributing guide so nobody adds CI steps that bypass Nx.

Troubleshooting checklist

  • Projects missing from the graph: Nx did not detect the settings file, or the project is not listed in include(...).
  • Stale or incorrect cache hits: a target has undeclared inputs, such as generated sources or environment variables, or undeclared outputs.
  • Slow first run: Gradle configuration time during graph computation. Later runs reuse the computed graph.
  • Inference or task failures after upgrades: the plugin and Gradle versions are mismatched.

Check the plugin documentation for your installed version, and revisit this configuration on every upgrade.

How OneEnv can help

Disclosure: OneEnv is the product behind this blog.

OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.

Applied to nx gradle plugin, this is where it helps:

Saves time

  • Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
  • One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
  • Changing a shared variable is one edit and one review instead of editing every service's .env by hand.

Saves cost

  • Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
  • Less duplicated configuration to maintain: one shared definition inherited by many services.
  • A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
  • OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.

These are qualitative benefits, not measured results — how much you save depends on how many services share the value.

Want to try it? Start at oneenv.io.