Nx with Maven

Apache Maven is a build tool for Java projects that uses a project object model (POM) to manage builds. Nx adds incremental builds, task caching, and the project graph on top of a Maven monorepo, so a multi-module workspace stays fast as it grows.

The @nx/maven plugin registers Maven modules as Nx projects so you can set up Maven with Nx, run daily Maven tasks, configure task inference, and run in CI.

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

Requirements

Dependency	Supported Versions
Java	>= 17
Maven	>= 3.6.0

Using older Java versions is unsupported and may lead to issues. If you need support for an older version, please create an issue on GitHub.

Setup

Install Nx

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

brew install nx

choco install nx

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

npm install --global nx@latest

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

Add Nx to a Maven Workspace

If you are in a Maven workspace without Nx, start here. This command adds Nx and configures @nx/maven:

nx init

Verify that Nx discovered your Maven modules:

nx show projects

nx show project my-app --web

Replace my-app with a module name from your workspace.

Add @nx/maven to an existing Nx workspace

If you already have an Nx workspace, add the Maven plugin:

nx add @nx/maven

Verify the plugin is active by inspecting a module:

nx show project my-app --web

Replace my-app with a module name from your workspace.

Local development

The plugin infers targets from Maven phases and plugin goals defined in your pom.xml files. By default, the target names are the Maven phase names:

nx compile my-module
nx test my-module
nx package my-module
nx verify my-module

If you configure a targetNamePrefix (for example mvn-), use the prefixed targets instead:

nx mvn-test my-module

Configuration

How @nx/maven infers tasks

The plugin scans your workspace for pom.xml files and analyzes the Maven build to create Nx targets for phases and plugin goals. A root pom.xml at the workspace root is required so the analyzer can resolve the Maven project tree.

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

nx show project my-module --web

@nx/maven configuration

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

{
  "plugins": [
    {
      "plugin": "@nx/maven",
      "options": {
        "targetNamePrefix": "mvn-",
        "verbose": false
      }
    }
  ]
}

Option	Type	Default	Description
`targetNamePrefix`	string	`undefined`	Prefix all inferred Maven targets to avoid name collisions in polyglot workspaces.
`verbose`	boolean	`false`	Enable verbose logging for the Maven analyzer. Also settable via `NX_VERBOSE_LOGGING=true`.

Exclude or include specific projects

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

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

There is no per-project disable for @nx/maven. To stop inference entirely, remove @nx/maven from the plugins array in nx.json.

Set up CI for your Maven monorepo

In CI, Nx runs nx affected to rebuild and retest only the projects a change touches, and caches results to skip repeated work.

For a complete pipeline, see Set up CI.

What's next

Java with Nx Learn how Nx supports Maven and Gradle together.

Gradle Plugin See the Nx plugin for Gradle.

Set Up CI Configure fast, reliable CI for Nx workspaces.

Maven Generators Reference Full reference for @nx/maven generators.

Maven Executors Reference Full reference for @nx/maven executors.