mvnpm locker Maven Plugin

The mvnpm locker Maven Plugin will create a version locker profile for your org.mvnpm and org.webjars dependencies. Allowing you to mimick the package-lock.json and yarn.lock files in a Maven world.

It is essential as NPM dependencies are typically deployed using version ranges, without locking your builds will use different versions of dependencies between builds if any of your transitive NPM based dependencies are updated.

In additon when using the locker, the number of files Maven need to download is considerably reduced as it no longer need to check all possible version ranges (better for reproducibility, contributors and CI).

Installation

IN_PROFILE Mode (for smaller amount of deps)

This command will modify your pom.xml with Locker dependencies directly in a new locker profile:

mvn io.mvnpm:locker-maven-plugin:LATEST:lock -Dlocker.mode=IN_PROFILE

LOCKER_BOM Mode (default)

This command will:

create a distinct Locker BOM file (./locker/pom.xml)
add a locker profile in your project pom.xml to use the Locker BOM

mvn io.mvnpm:locker-maven-plugin:LATEST:lock

Now you need to install the locker BOM in the Maven local repository (It is required before building your project):

=> On a standalone project:

Manually mvn -f locker clean install. Add it to your install doc and add as a new step in your CI.
Using the locker extension to automate this.

=> On multi-module project, add the locker bom as a module in the parent pom.xml:

      <modules>
        ...
        <module>my-module/locker</module>
        <module>my-module</module>
        ...
      </modules>

Update your locked dependencies

To update, you need to add -Dunlocked alongside the lock goal (to disable the locker profile and find new versions):

mvn io.mvnpm:locker-maven-plugin:LATEST:lock -Dunlocked

NOTE: You don't need to specify the mode (-Dlocker.mode option) as it is auto-detected.

Switch to Locker BOM Mode (from in-profile locker dependencies)

If the amount of dependencies in your project has grown, you may want to switch to the Locker BOM Mode (to reduce the amount of dependencies in your project pom.xml).

mvn io.mvnpm:locker-maven-plugin:LATEST:lock -Dunlocked -Dlocker.mode=LOCKER_BOM

For the opposite, you can just remove the Locker BOM from your project and the locker profile and use the -Dlocker.mode=IN_PROFILE option to add the locker dependencies to your project pom.xml.

Add the locker extension for Locker BOM mode (optional)

This extension is optional, it is important for standalone projects to make sure your BOM is installed before running the project (for example when a new contributor clone the project and runs it or in CI).

.mvn/extensions.xml

<extensions xmlns="http://maven.apache.org/EXTENSIONS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://maven.apache.org/EXTENSIONS/1.0.0 http://maven.apache.org/xsd/core-extensions-1.0.0.xsd">
    <extension>
        <groupId>io.mvnpm</groupId>
        <artifactId>locker-maven-plugin</artifactId>
        <version>1.0.0</version>
    </extension>
</extensions>

Features:

Install the Locker BOM (locker/pom.xml) in the local Maven repository if out-of-date before loading the Maven project (on any goal but lock)
Ignore the locker profile when using the lock goal.

Common issues

Maven resolver can't determine which version to use between two versions?

In that case, choose which version to use by adding this dependency in the pom.xml dependencyManagement > dependencies section.

Dependabot update fails to build because of missing transitive dependencies

We are working on making this process automatic (See https://github.com/mvnpm/mvnpm/issues/4614), but for now you have two options:

a. Checkout the PR locally and use mvnpm-repo profile to build. It will make sure all missing transitive dependencies are synchronized on Maven Central.
b. Configure your CI to use the mvnpm-repo on dependabot updates PRs.

mvnpm / locker

readme