Maven Plugin Configuration

The OpenRewrite Maven Plugin is the fastest way to apply OpenRewrite recipes to your code as part of your Maven build. The OpenRewrite Maven Plugin is compatible with all versions of Maven since 3.6.
The OpenRewrite Maven plugin automatically supplies any recipes you configure to run with all source files in the project that are transformable. It will supply Java visitors with Java files, XML visitors with XML files, etc.
The OpenRewrite Maven plugin offers these goals:
mvn rewrite:run - Run the configured recipes and apply the changes locally.
mvn rewrite:dryRun - Generate warnings to the console for any recipe that would make changes, but do not make changes.
mvn rewrite:discover - Generate a report of available recipes found on the classpath.
mvn rewrite:cyclonedx - Generate a CycloneDx bill of materials outlining the project's dependencies, including transitive dependencies.
In some circumstances, depending on how your project pom.xml is configured, you may get a NoPluginFoundForPrefixException. The root cause for this varies from pom.xml to pom.xml. In any case, as a quick fix to get unstuck, try referencing the fully-qualified rewrite-maven-plugin coordinates instead of the shorthand prefix. That is, try using mvn org.openrewrite.maven:rewrite-maven-plugin:GOAL (such as mvn org.openrewrite.maven:rewrite-maven-plugin:run, etc.) rather than mvn rewrite:GOAL.
Plugin configuration
It generally makes sense to apply the plugin to the root pom.xml in a repository so that the configuration applies to each project in a multi-module project. The configuration block below contains an example of every configuration option.
activeRecipes - Explicitly turns on recipes by name (the name given in the specs.openrewrite.org/v1beta/recipe resource). No recipe is run unless explicitly turned on with this setting.
activeStyles - Explicitly turns on a style by name (the name given in the specs.openrewrite.org/v1beta/style resource). No style is applied unless explicitly turned on with this setting.
configLocation - Where to look for a OpenRewrite YML configuration file somewhere in the project directory (or really anywhere on disk). If you want to customize this, prefixing the file name with the Maven property ${maven.multiModuleProjectDirectory} is a handy way of ensuring that each module resolves the same configuration file relative to the root directory of the repository. This configLocation is (unless an absolute path is given) evaluated for each module relative to that module's project directory.
failOnDryRunResults - Boolean flag toggling whether rewrite:dryRun should throw an exception and non-zero exit code if changes are detected. Default is false.
dependencies - To make pre-packaged OpenRewrite recipes available to the Maven plugin, add them as plugin dependencies.
Note. the plugin scans the compile, provided, and test scopes for visitors, recipes, and styles and will automatically discover recipes on the project classpath.
pom.xml
1
<project>
2
  <build>
3
    <plugins>
4
      <plugin>
5
        <groupId>org.openrewrite.maven</groupId>
6
        <artifactId>rewrite-maven-plugin</artifactId>
7
        <version>4.12.0</version>
8
        <configuration>
9
          <activeRecipes>
10
            <recipe>org.openrewrite.java.Spring</recipe>
11
          </activeRecipes>
12
          <activeStyles>
13
            <!-- This style is made up for sake of example. It isn't packaged with OpenRewrite -->
14
            <style>com.yourorg.SpringStyle</style>
15
          </activeStyles>
16
          <!-- These are default values, shown for example. It isn't necessary to supply these values manually: -->
17
          <configLocation>${maven.multiModuleProjectDirectory}/rewrite.yml</configLocation>
18
          <failOnDryRunResults>false</failOnDryRunResults>
19
        </configuration>
20
        <dependencies>
21
          <!-- This module is made up for sake of example. It isn't packaged with OpenRewrite -->
22
          <dependency>
23
            <groupId>com.yourorg.recipes</groupId>
24
            <artifactId>your-recipes</artifactId>
25
            <version>1.0.0</version>
26
          </dependency>
27
        </dependencies>
28
      </plugin>
29
    </plugins>
30
  </build>
31
</project>
Copied!
To find out what recipes a rewrite module provides, see its documentation and the output of the rewrite:discover goal.
The "Run" Goal
Execute mvn rewrite:run to run the active recipes and apply the changes. This will write changes locally to your source files on disk. Afterward, review the changes, and when you are comfortable with the changes, commit them. The run goal generates warnings in the build log wherever it makes changes to source files.
Warnings showing which files were changed and by what visitors
After the goal finishes executing, run git diff to see what changes were made, review, and commit them.
An example of changes made to spring-cloud/spring-cloud-sleuth the rewrite:run goal
The "dryRun" Goal
Execute mvn rewrite:dryRun to dry-run the active recipes and print which visitors would make changes to which files to the build log. This does not alter your source files at all. This goal can be used to preview the changes that would be made by a recipe.
rewrite:dryRun outputs a report in the form of a patch file, by default under target/site/rewrite/rewrite.patch, containing changes that would be made if you were to run rewrite:run. This file can be used with git or diff to view or apply the potential changes. For example, git diff . target/site/rewrite/rewrite.patch.
Example rewrite.patch file produced by dryRun
dryRun can be used as a "gate" in a continuous integration environment by failing the build if dryRun detects changes to be made and failOnDryRunResults is set to true:
1
<configuration>
2
  <failOnDryRunResults>true</failOnDryRunResults>
3
</configuration>
Copied!
If desired, dryRun can be configured to bind dryRun to desired maven phases. For example, the following configuration is sufficient to have mvn verify also run rewrite:dryRun:
1
<!-- truncating the pom.xml for brevity -->
2
<project>
3
  <build>
4
    <plugins>
5
      <plugin>
6
        <artifactId>rewrite-maven-plugin</artifactId>
7
        <configuration>...</configuration>
8
        <!-- this 'executions' block is the important part of binding the dryRun goal to the verify phase -->
9
        <executions>
10
          <execution>
11
            <goals>
12
              <goal>dryRun</goal>
13
            </goals>
14
            <phase>verify</phase>
15
          </execution>
16
        </executions>
17
      </plugin>
18
    </plugins>
19
  </build>
20
</project>
Copied!
The "Discover" Goal
Execute mvn rewrite:discover to list the recipes that the OpenRewrite Maven plugin has found on your classpath and the recipes that you have activated in your plugin configuration.
The beginning of rewrite:discover output, showing activated and available Recipes
This same goal also lists all of the parameters that recipes can be or are already configured with.
Recipes showing their configurable parameters. "!" means a parameter is required.
The "CycloneDx" Goal
Execute rewrite:cyclonedx to generate a CycloneDx bill of materials (BOM) outlining all of the project's dependencies, including transitive dependencies. The BOM will be written to target/<module name>-<version>-cyclonedx.xml.
Excerpt from OpenRewrite-generated CycloneDx BOM
Links
​Github project​
​Issue Tracker​

Reference - Previous

Latest versions of every OpenRewrite module

Next - Reference

Gradle Plugin Configuration

Last modified 30d ago

Export as PDF

Copy link

Contents