The Apollo compiler supports a wide range of options. For the cases where these options are not enough, you can use Apollo compiler plugins to modify the behaviour of the compiler.

Apollo compiler plugins allow to:

• Change the layout of the generated sources (name of the classes, package names, capitalization rules).
• Change the ids of operation for persisted queries.
• Transform the JavaPoet/KotlinPoet models.
• Transform the Apollo IR.

Implementing a compiler plugin

In this example we will implement a plugin that uses custom persisted queries ids registered on your backend.

The Apollo compiler use the ServiceLoader API to load plugins at runtime. Plugins need to be implemented in a separate module that is added to the classpath.

To start, create a new Gradle module and add apollo-compiler as a dependency to the module build.gradle[.kts] file. In this example, we'll use apollo-compiler-plugin for the module name:

1
// apollo-compiler-plugin/build.gradle.kts
2
plugins {
3
  id("org.jetbrains.kotlin.jvm")
4
}
5

6
dependencies {
7
  // Add apollo-compiler as a dependency
8
  implementation("com.apollographql.apollo3:apollo-compiler:4.0.0-beta.4")  
9
}

Next create your plugin in a src/main/kotlin/mypackage/MyPlugin file:

1
package mypackage
2

3
import com.apollographql.apollo3.compiler.OperationOutputGenerator
4
import com.apollographql.apollo3.compiler.Plugin
5
import com.apollographql.apollo3.compiler.operationoutput.OperationDescriptor
6
import com.apollographql.apollo3.compiler.operationoutput.OperationId
7

8
class MyPlugin: Plugin {
9
  override fun operationIds(descriptors: List<OperationDescriptor>): List<OperationId> {
10
    // This assumes the returned ids are in the same order as the descriptors
11
    return registerOperations(descriptors).withIndex().map { OperationId(it.value, descriptors[it.index].name) }
12
  }
13

14
  /**
15
   * Send operations to a remote server and return the server persisted ids 
16
   */
17
  fun registerOperations(descriptors: List<OperationDescriptor>): List<String> {
18
    // ...
19
  }
20
}

Make your plugin discoverable by ServiceLoader using a resource in src/main/resources/META-INF/services/com.apollographql.apollo3.compiler.Plugin. This file contains the fully qualified name of your plugin:

1
mypackage.MyPlugin

Adding a plugin to the Apollo compiler classpath

Use the Service.plugin() Gradle method to add the plugin to the Apollo compiler classpath:

1
// app/build.gradle.kts
2
plugins {
3
  id("org.jetbrains.kotlin.jvm")
4
  id("com.apollographql.apollo3")
5
}
6

7
apollo {
8
  service("service") {
9
    packageName.set("com.example")
10
    
11
    // Add your plugin to the Apollo compiler classpath
12
    plugin(project(":apollo-compiler-plugin")) 
13
  }
14
}

The plugin code will now be invoked the next time the compiler is invoked.

Other references

For other plugin APIs like layout, IR, JavaPoet and KotlinPoet transforms, check out the Plugin API docs

For more examples, check out the integration-tests.