OpenRewrite: running recipe-based refactors with the Maven and Gradle plugins

What OpenRewrite changes and who ends up using it

The problem is the refactor nobody wants to own: a framework upgrade, a deprecated API call spread across a few hundred files, or a style rule that has drifted. OpenRewrite packages those changes as recipes and runs them through an auto-refactoring engine. The README frames the payoff as reducing coding effort from hours or days to minutes, and the repository is organised around that single claim.

The intended user is a developer or platform engineer with a Java codebase and a build they already trust. The Maven and Gradle plugins are the entry point, and the README describes them as running one recipe at a time against a single repository. That phrase is doing real work. It tells you the unit of work is a repository, not an organisation.

Recipes are also meant to be edited. The README says they are easy to customize and that you can write your own, which matters if the catalog covers the migration you need but not the local convention you have adopted on top of it.

The Lossless Semantic Tree is the whole mechanism

OpenRewrite does not pattern-match on text. It builds a Lossless Semantic Tree, described in the documentation as a type-aware model of your source code, and builds it in memory each time a recipe runs. Lossless means the tree retains formatting and other details that a plain AST drops, so a recipe can change one node and print the file back without reformatting everything around it.

Type-aware is the part that decides whether a recipe works. A recipe that rewrites calls to a particular method needs to know which method a call site actually resolves to, not just its name. That resolution depends on the classpath the engine can see. The README notes that the LST is rebuilt on every run, which is why the same engine behaves differently across repositories: one project resolves cleanly, another has generated sources or a dependency the parser cannot load, and the recipe quietly touches less code.

The repository layout reflects the same design. Parsers are split by language into directories such as rewrite-java, rewrite-kotlin, rewrite-groovy, rewrite-javascript, rewrite-python and rewrite-csharp, with rewrite-core holding the framework and rewrite-test holding test support. Java version support is split further into rewrite-java-8, rewrite-java-11, rewrite-java-17, rewrite-java-21 and rewrite-java-25.

Installing the Maven plugin and running a first recipe

The README points to the quickstart guide in the documentation and to the plugin reference pages for configuration, so the plugin is the documented install path. The README names the OpenRewrite Maven Plugin and the OpenRewrite Gradle Plugin and links their configuration references, but it does not print a pom.xml snippet or a goal name, so the exact plugin coordinates and invocation come from those reference pages rather than from anything quoted here. Read the Maven plugin reference before editing your build file.

What the README does establish is the shape of the work: you declare the plugin in your build, attach one or more recipes to it, and run it against the repository. The recipe identifiers themselves live in the catalog the documentation links to, and the licensing page is where the README says the split between framework and recipe licensing is settled.

What you should expect on a first run is a parse-heavy pass followed by edits to your working tree. Because the LST is built in memory every time, a large project spends most of that first run constructing the tree. Review the result with git diff before committing. The Gradle plugin covers the same ground for Gradle builds through its own configuration reference.

Where the single-repository boundary bites

The most concrete limitation is stated plainly in the README: OpenRewrite is built to migrate, secure and refactor code one repository at a time, and Moderne is the commercial platform that runs the same recipes across hundreds or thousands of repositories at once. If your actual problem is a dependency version pinned identically in four hundred services, the open engine gives you a recipe and a per-repository run, not a fleet-wide execution. You supply the loop.

The second boundary is language. The README says the parsers and base recipes for the additional languages are open source, but running recipes against them requires a Moderne license. So the presence of rewrite-python or rewrite-csharp in the repository tree does not mean you can point the open Maven plugin at a Python service and expect the same experience as Java.

The third is the LST build itself. Every run reparses the code in memory. On a repository where type resolution fails, a recipe can complete without error and still leave the code you wanted changed untouched, because the nodes it was looking for never resolved. That failure is quiet, and it is the reason the diff deserves a real read.

Finally, the README does not document rollback. The engine edits files in your working tree, so version control is the recovery mechanism, and a dirty working tree before you run is a bad starting position.

OpenRewrite against a plain code formatter

The obvious comparison is a formatter such as google-java-format or Spotless. Those tools operate on syntax and whitespace: they reflow code to a fixed style and stop there. They cannot rename a deprecated method across a codebase, because that requires knowing which method each call site resolves to.

OpenRewrite's type-aware LST is what separates the two. A recipe can be written against a specific type and applied only where that type is in play, which is why the same engine handles both stylistic consistency tasks and framework migrations. The trade-off runs the other way too. A formatter needs no classpath and no resolution, so it never silently skips a file. OpenRewrite pays for its reach with a parse step that can fail to resolve, and with run times dominated by building the tree rather than by applying the change.

A second reference point is the commercial platform itself. Moderne batch-builds LSTs once and serialises them so they can be reused across repositories and teams without rebuilding, and exposes that same tree to coding agents through tools the README names as Prethink, Trigrep and a local MCP server. That is the same engine with the parse cost amortised. The open plugins rebuild the tree on every run, which is the price of not having the platform.

Maintenance, releases and what the Apache-2.0 licence covers

The latest release listed is v8.91.2 on 2026-08-28, with v8.91.1 and v8.91.0 in the two days before it. The last push to main was on 2026-08-28. That release cadence, roughly a patch every day or two across that window, is worth knowing before you pin a version: the plugin version moves, and a recipe's behaviour can shift between patches. Pinning an exact plugin version in your build file and reading the release notes before bumping is the cheap insurance.

On licensing, the README states that the core framework is Apache-2.0 and will always be open source, and that many recipes in the catalog are too. It does not claim all of them are. The README explicitly directs readers to the licensing page in the documentation for how the framework and recipes are licensed, which is the only place that distinction is settled. That is not legal advice, and the split between framework and recipe licensing is exactly the kind of thing your own review process should confirm rather than assume from the repository's Apache-2.0 badge.

Editorial conclusion

Adopt OpenRewrite if you maintain a Java repository and want migrations, security fixes and style changes expressed as named, repeatable recipes rather than manual edits. The Maven and Gradle plugins cover that case, and the core framework stays Apache-2.0. Do not adopt it expecting the same recipe to sweep hundreds of repositories, and do not expect to run the JavaScript, Python or C# recipes without a Moderne license. Before committing, verify two things: that the recipe you intend to run lives in the open catalog rather than behind the platform, and that your repository builds cleanly enough for the LST to resolve types, since a recipe that cannot resolve a type will skip the code it was meant to change.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes