OpenRewrite

OpenRewrite is a tool for running recipes for common framework migrations, security fixes, and stylistic consistency tasks. For example, it can automate migration to a new framework version by modifying build files, changing deprecated API, and migrating configuration settings.

In Gradle and Maven projects, IntelliJ IDEA provides integration with OpenRewrite including coding assistance, a dedicated run configuration, and actions designed to ease the process of creating and executing OpenRewrite recipes.

Create OpenRewrite recipe

In the Project tool window, right-click a folder (or press Alt+Insert) and select New | OpenRewrite Recipe.
Alternatively, in the main menu, go to Refactor | Migrate Packages and Classes | Create New OpenRewrite Migration. This will create a recipe file under Scratches and Consoles | Scratches. As a scratch file, it won't be part of the project; instead, it will be available in any project opened with this instance of IntelliJ IDEA.
In the New OpenRewrite Recipe dialog that opens, enter the name for the new recipe file and press Enter.
This will create a new recipe file based on the dedicated file template.
Provide a fully-qualified, unique name and, under recipeList, start typing the names of the recipes you want to add.
IntelliJ IDEA provides you with OpenRewrite coding assistance, which includes autocompletion for known recipe names, quick documentation lookup, and inlay hints with recipe descriptions.

Run OpenRewrite recipe

Open an OpenRewrite recipe file.
In the gutter, click .

You can check the execution output in the Run tool window.

When the migration is completed, click Show changes to preview the list of modified files. Click any of them to view what changes have been made to it.

If this is the first time you run the recipe, IntelliJ IDEA creates a temporary run configuration that you can customize.

Run built-in migration recipes

For some frameworks, IntelliJ IDEA provides migration recipes that you can run directly from your build files, saving you the trouble of manually writing a recipe. This is available for Spring versions lower than 3, Quarkus versions lower than 2, and Micronaut versions 3 or lower.

Open your build file: pom.xml or build.gradle(.kts).
Click the OpenRewrite icon in the toolbar in the right part of the editor.
Alternatively, in the Project tool window, right-click your build file and select Refactor | Run OpenRewrite Migration.
In the list that opens, select a recipe.

This will run the selected migration recipe.

Expand complex recipes

A recipe can represent a single operation, or it can consist of multiple other recipes. For example, the UpgradeSpringBoot_3_2 recipe includes over a dozen other recipes: besides upgrading Gradle or Maven dependency versions of Spring Boot, you have to migrate Spring Security, Spring Data, update API elements, and so on.

With IntelliJ IDEA, you can retrieve and preview such recipes that are component parts of more complex recipes. This allows you, for example, to remove certain stand-alone operations if you want to delay some parts of a larger migration, or if you prefer to implement these changes manually.

In your OpenRewrite YAML file, place the caret at the recipe name and press Alt+Enter (Show Context Actions).
Select Inline recipe. The action is available if the recipe consists of other recipes.

OpenRewrite run configuration

IntelliJ IDEA comes with a dedicated OpenRewrite run configuration. When you run a recipe using the gutter icon for the first time, IntelliJ IDEA creates a temporary run configuration.

If you want to customize how IntelliJ IDEA launches the recipe, you can modify this run configuration or create a new one: go to Run | Edit Configurations or press Alt+Shift+F10.

Main parameters

Name: Specify a name for the run configuration.
Store as project file: Save the run configuration settings to a file that you can share with other team members. The default location is .idea/runConfigurations. However, if you do not want to share the .idea directory, you can save the configuration to any other directory within the project.
Working directory: Directory where you want to run the recipes.
Active recipes: Recipes to run. Start typing the name to get completion for your local recipe name and names of applicable recipes from the OpenRewrite catalog.

Logs

Specify which log files generated while running the application should be displayed in the console on the dedicated tabs of the Run tool window.

OpenRewrite modify options

Active styles

List of OpenRewrite styles to apply. Similarly to recipes, you can enter the name of your local style, or start typing a name to get completion for styles from the OpenRewrite catalog.

Config location

Specify a custom location of the OpenRewrite configuration file.

Exclusions

Specify files or paths to exclude OpenRewrite operations, for example **/internal/**.

Plain text masks

Set of file masks to denote which files should be parsed as plain text.

OpenRewrite version

Customize the version of the Maven/Gradle OpenRewrite plugin to be used.

Add VM options

VM options to be passed to the Java virtual machine when launching the application.

Environment variables

Set environment variables for the Maven goal or the Gradle task used for the OpenRewrite recipe execution.

Dry run

Run the dryRun task (for Gradle) or the dryRun goal (for Maven) to preview the changes that would be made by a recipe, without actually altering any files.

You can locate the path to the Dry run report in the Run tool window.

Before launch

Select tasks to be performed before starting the selected run/debug configuration.

Last modified: 25 June 2024