Recipe Development Environment

This getting started guide covers setting up your development environment for creating your own OpenRewrite recipes.
Prerequisites
​JDK (version 1.8+)
A JRE alone is insufficient since OpenRewrite uses compiler internals and tools only found in the JDK
​Gradle (version 4.0+ ) or Maven (version 3.2+)
Text Editor or IDE with Java support. Kotlin support optional but recommended for a good test authoring experience
​IntelliJ​
​Eclipse with Kotlin Plugin​
Project Setup
Gradle and Maven both provide helpful commands for initializing a new project. Either of these commands will lay out an appropriate directory structure and a basic build.gradle or pom.xml.
Gradle
Maven
1
gradle init
Copied!
1
mvn -B archetype:generate -DgroupId=com.mycompany.app -DartifactId=my-app -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4
Copied!
Dependencies
Which rewrite libraries you take dependencies on is determined by which languages/data formats you want to write Recipes for.
Gradle
Maven
1
dependencies {
2
    // rewrite-java dependencies only necessary for Java Recipe development
3
    implementation("org.openrewrite:rewrite-java:7.15.0")
4
    runtimeOnly("org.openrewrite:rewrite-java-11:7.15.0")
5
    runtimeOnly("org.openrewrite:rewrite-java-8:7.15.0")
6
​
7
    // rewrite-maven dependency only necessary for Maven Recipe development
8
    implementation("org.openrewrite:rewrite-maven:7.15.0")
9
​
10
    // rewrite-yaml dependency only necessary for Yaml Recipe development
11
    implementation("org.openrewrite:rewrite-yaml:7.15.0")
12
​
13
    // rewrite-properties dependency only necessary for Properties Recipe development
14
    implementation("org.openrewrite:rewrite-properties:7.15.0")
15
​
16
    // rewrite-xml dependency only necessary for XML Recipe development
17
    implementation("org.openrewrite:rewrite-xml:7.15.0")
18
​
19
    // For authoring tests for any kind of Recipe
20
    testImplementation("org.openrewrite:rewrite-test:7.15.0")
21
}
Copied!
1
<dependencies>
2
    <!-- rewrite-java depedencies only necessary for Java Recipe development -->
3
    <dependency>
4
        <groupId>org.openrewrite</groupId>
5
        <artifactId>rewrite-java</artifactId>
6
        <version>7.15.0</version>
7
        <scope>compile</scope>
8
    </dependency>
9
    <dependency>
10
        <groupId>org.openrewrite</groupId>
11
        <artifactId>rewrite-java-8</artifactId>
12
        <version>7.15.0</version>
13
        <scope>runtime</scope>
14
    </dependency>
15
    <dependency>
16
        <groupId>org.openrewrite</groupId>
17
        <artifactId>rewrite-java-11</artifactId>
18
        <version>7.15.0</version>
19
        <scope>runtime</scope>
20
    </dependency>
21
​
22
    <!-- rewrite-maven dependency only necessary for Maven Recipe development -->
23
    <dependency>
24
        <groupId>org.openrewrite</groupId>
25
        <artifactId>rewrite-maven</artifactId>
26
        <version>7.15.0</version>
27
        <scope>compile</scope>
28
    </dependency>
29
​
30
    <!-- rewrite-yaml dependency only necessary for Yaml Recipe development -->
31
    <dependency>
32
        <groupId>org.openrewrite</groupId>
33
        <artifactId>rewrite-yaml</artifactId>
34
        <version>7.15.0</version>
35
        <scope>compile</scope>
36
    </dependency>
37
​
38
    <!-- rewrite-properties dependency only necessary for Properties Recipe development -->
39
    <dependency>
40
        <groupId>org.openrewrite</groupId>
41
        <artifactId>rewrite-properties</artifactId>
42
        <version>7.15.0</version>
43
        <scope>compile</scope>
44
    </dependency>
45
​
46
    <!-- rewrite-xml dependency only necessary for XML Recipe development -->
47
    <dependency>
48
        <groupId>org.openrewrite</groupId>
49
        <artifactId>rewrite-xml</artifactId>
50
        <version>7.15.0</version>
51
        <scope>compile</scope>
52
    </dependency>    
53
​
54
    <!-- For authoring tests for any kind of Recipe -->
55
    <dependency>
56
        <groupId>org.openrewrite</groupId>
57
        <artifactId>rewrite-test</artifactId>
58
        <version>7.15.0</version>
59
        <scope>test</scope>
60
    </dependency>
61
</dependencies>
Copied!
rewrite-test uses JUnit 5.
rewrite-java-11 and rewrite-java-8 can happily coexist on the same classpath. At runtime the appropriate module for the current JDK will be selected.
Set Language Level and Bytecode Level
In order to be able to use OpenRewrite to modernize old projects it's important to be able to run on older JDK implementations. So configure the Java compiler to target Java Language and Bytecode level 1.8.
Gradle
Maven
build.gradle
1
// See https://docs.gradle.org/current/userguide/building_java_projects.html#sec:java_cross_compilation
2
tasks.withType(JavaCompile) {        
3
    sourceCompatibility = JavaVersion.VERSION_1_8.toString()
4
    targetCompatibility = JavaVersion.VERSION_1_8.toString()
5
}
Copied!
pom.xml
1
  <!-- see https://maven.apache.org/plugins/maven-compiler-plugin/examples/set-compiler-source-and-target.html -->
2
  <properties>
3
    <maven.compiler.source>1.8</maven.compiler.source>
4
    <maven.compiler.target>1.8</maven.compiler.target>
5
  </properties>
Copied!
Kotlin Plugin (Optional)
For a good test authoring experience we recommend also applying the Kotlin plugin.
Gradle
Maven
build.gradle
1
// https://kotlinlang.org/docs/gradle.html#targeting-the-jvm
2
plugins {
3
    id("org.jetbrains.kotlin.jvm") version("1.5.10")
4
}
Copied!
pom.xml
1
<!-- https://kotlinlang.org/docs/maven.html -->
2
<properties>
3
    <kotlin.version>1.4.31</kotlin.version>
4
</properties>
5
​
6
<dependencies>
7
    <dependency>
8
        <groupId>org.jetbrains.kotlin</groupId>
9
        <artifactId>kotlin-stdlib</artifactId>
10
        <version>${kotlin.version}</version>
11
    </dependency>
12
</dependencies>
13
​
14
<build>
15
    <plugins>
16
        <plugin>
17
            <groupId>org.jetbrains.kotlin</groupId>
18
            <artifactId>kotlin-maven-plugin</artifactId>
19
            <version>${kotlin.version}</version>
20
            <executions>
21
                <execution>
22
                    <id>compile</id>
23
                    <goals>
24
                        <goal>compile</goal>
25
                    </goals>
26
                    <configuration>
27
                        <sourceDirs>
28
                            <sourceDir>${project.basedir}/src/main/kotlin</sourceDir>
29
                            <sourceDir>${project.basedir}/src/main/java</sourceDir>
30
                        </sourceDirs>
31
                    </configuration>
32
                </execution>
33
                <execution>
34
                    <id>test-compile</id>
35
                    <goals> <goal>test-compile</goal> </goals>
36
                    <configuration>
37
                        <sourceDirs>
38
                            <sourceDir>${project.basedir}/src/test/kotlin</sourceDir>
39
                            <sourceDir>${project.basedir}/src/test/java</sourceDir>
40
                        </sourceDirs>
41
                    </configuration>
42
                </execution>
43
            </executions>
44
        </plugin>
45
        <plugin>
46
            <groupId>org.apache.maven.plugins</groupId>
47
            <artifactId>maven-compiler-plugin</artifactId>
48
            <version>3.5.1</version>
49
            <executions>
50
                <!-- Replacing default-compile as it is treated specially by maven -->
51
                <execution>
52
                    <id>default-compile</id>
53
                    <phase>none</phase>
54
                </execution>
55
                <!-- Replacing default-testCompile as it is treated specially by maven -->
56
                <execution>
57
                    <id>default-testCompile</id>
58
                    <phase>none</phase>
59
                </execution>
60
                <execution>
61
                    <id>java-compile</id>
62
                    <phase>compile</phase>
63
                    <goals>
64
                        <goal>compile</goal>
65
                    </goals>
66
                </execution>
67
                <execution>
68
                    <id>java-test-compile</id>
69
                    <phase>test-compile</phase>
70
                    <goals>
71
                        <goal>testCompile</goal>
72
                    </goals>
73
                </execution>
74
            </executions>
75
        </plugin>
76
    </plugins>
77
</build>
Copied!
Throughout OpenRewrite's documentation Java is used for Recipe authoring and Kotlin is used for test authoring. You do not have to be constrained by this recommendation: Recipes and tests can be authored in any language that runs on the JVM.
Project Layout
Having configured the project per these recommendations, you're now able to begin Recipe development. With Gradle and Maven's default project layout, here is where to put the various kinds of sources that go into a OpenRewrite Module:
src/main/java - Recipe implementations in Java
src/main/kotlin - Recipe implementations in Kotlin
src/main/resources/META-INF/rewrite - Yaml files defining declarative OpenRewrite Recipes
src/test/java - Recipe tests in Java
src/test/kotlin - Recipe tests in Kotlin
Project setup is complete. You are ready to move on to authoring a Recipe!
Recipe Distribution
With your project set up as instructed by this guide the jar produced by your build is ready to be consumed as a rewrite module. Once published to an artifact repository like Maven Central, other projects can take a dependency on your OpenRewrite module and activate the recipes contained therein.
Next Steps
​Writing a Java Refactoring Recipe​
​Maven Plugin Configuration​
​Gradle Plugin Configuration​

Getting Started - Previous

Quickstart: Maven and Gradle

Next - Tutorials & Guides

Common Static Analysis Issue Remediation

Last modified 10d ago

Export as PDF

Copy link

Contents

Prerequisites

Project Setup

Dependencies

Set Language Level and Bytecode Level

Kotlin Plugin (Optional)

Project Layout

Recipe Distribution

Next Steps