Join us from October 8-10 in New York City to learn the latest tips, trends, and news about GraphQL federation and API platform engineering.Join us for GraphQL Summit 2024 in NYC
Docs
Start for Free

Apollo compiler plugins


Compiler plugins are currently experimental in Apollo Kotlin. If you have feedback on them, please let us know via GitHub issues or in the Kotlin Slack community.

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 for .
  • 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 as module name:

// apollo-compiler-plugin/build.gradle.kts
plugins {
id("org.jetbrains.kotlin.jvm")
}
dependencies {
// Add apollo-compiler as a dependency
implementation("com.apollographql.apollo3:apollo-compiler:4.0.0-beta.7")
}

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

package mypackage
import com.apollographql.apollo3.compiler.OperationOutputGenerator
import com.apollographql.apollo3.compiler.ApolloCompilerPlugin
import com.apollographql.apollo3.compiler.operationoutput.OperationDescriptor
import com.apollographql.apollo3.compiler.operationoutput.OperationId
class MyPlugin: ApolloCompilerPlugin {
override fun operationIds(descriptors: List<OperationDescriptor>): List<OperationId> {
// This assumes the returned ids are in the same order as the descriptors
return registerOperations(descriptors).withIndex().map { OperationId(it.value, descriptors[it.index].name) }
}
/**
* Send operations to a remote server and return the server persisted ids
*/
fun registerOperations(descriptors: List<OperationDescriptor>): List<String> {
// ...
}
}

Next, create an ApolloCompilerPluginProvider. This is the entry point of compiler plugins. It is loaded using the ServiceLoader API.

class MyPluginProvider: ApolloCompilerPluginProvider {
override fun create(environment: ApolloCompilerPluginEnvironment): ApolloCompilerPlugin {
return MyPlugin()
}
}

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

mypackage.MyPluginProvider

NOTE

The name of the resource file is important. It must be com.apollographql.apollo3.compiler.ApolloCompilerPluginProvider and be in the META-INF/services folder. This is how ServiceLoader looks up plugins at runtime.

Adding a plugin to the Apollo compiler classpath

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

// app/build.gradle.kts
plugins {
id("org.jetbrains.kotlin.jvm")
id("com.apollographql.apollo3")
}
apollo {
service("service") {
packageName.set("com.example")
// Add your plugin to the Apollo compiler classpath
plugin(project(":apollo-compiler-plugin"))
}
}

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

Passing arguments to your Apollo compiler plugin

Because the compiler plugin runs in an isolated classpath, you can't use classes or data from your main build logic classpath.

In order to pass build-time to your Apollo compiler plugin, use the argument() function:

apollo {
service("service") {
packageName.set("com.example")
// Add your plugin to the Apollo compiler classpath
plugin(project(":apollo-compiler-plugin")) {
argument("token", token)
}
}
}

The arguments are available in ApolloCompilerPluginEnvironment.arguments:

class MyPluginProvider: ApolloCompilerPluginProvider {
override fun create(environment: ApolloCompilerPluginEnvironment): ApolloCompilerPlugin {
return MyPlugin(environment.arguments.get("token") as String)
}
}

must be serializable and be instances of classes accessible from the bootstrap classloader. In practice, built-in types and collections are supported.

Limitations

Because codegen is run in a separate classloader when using compiler plugins, it's not possible to use packageNameGenerator, operationIdGenerator or operationOutputGenerator at the same time as compiler plugins. If you want to use them, you'll have to:

  • use ApolloCompilerPlugin.layout() instead of packageNameGenerator
  • use ApolloCompilerPlugin.operationIds() instead of operationIdGenerator and operationOutputGenerator

Other references

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

For more examples, check out the integration-tests.

Previous
Apollo AST
Next
JS Interoperability
Rate articleRateEdit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company