Overview of the Nx Plugin for Maven

Experimental Plugin

The @nx/maven plugin is currently experimental. Features and APIs may change.

Apache Maven is a build tool for Java projects that uses a project object model (POM) to manage builds.

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.

Setup

Prerequisites

• Java 17 or newer
• Maven 3.6.0 or newer

Install Nx

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

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

npm

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.

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:

nx.json

{
  "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.

CI Considerations

Build and test only what changed using the project graph:

nx affected -t test package

Connect Nx Cloud to share cache results and speed up Maven builds in CI:

nx connect

Batch Mode

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

NX_BATCH_MODE=true nx run-many -t build test

See Set Up CI for a complete configuration guide.

If you use Maven profiles or parallel builds in CI, define them in .mvn/maven.config (for example -Pci or -T1C) so Nx runs the same settings consistently.

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.