-
Notifications
You must be signed in to change notification settings - Fork 645
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[📚doc] docs for 4.0.0-beta.5 (#5601)
* update docs * add HTTP headers docs * Start drafting the changelog * add compiler-plugin doc * add doc for Apollo compiler plugins * cosmetics * cosmetics * bump nullability in the next docs * deprecate schemaFile * dd all changes to the changelog * use simple dependsOn() in docs * add highlights * bump nullability version * This entry was part of the more general compiler plugins effort * add 3.8.3 changelog * remove 3.8.3 and add bullet points * tweaks * add links * add link * Update docs/source/advanced/compiler-plugins.mdx Co-authored-by: Benoit 'BoD' Lubek <BoD@JRAF.org> * Update docs/source/advanced/compiler-plugins.mdx Co-authored-by: Benoit 'BoD' Lubek <BoD@JRAF.org> * Update docs/source/advanced/compiler-plugins.mdx Co-authored-by: Benoit 'BoD' Lubek <BoD@JRAF.org> * use our own <Note> * fix Note syntax * better <Note> syntax --------- Co-authored-by: BoD <BoD@JRAF.org>
- Loading branch information
1 parent
a91447f
commit d1a7021
Showing
7 changed files
with
254 additions
and
77 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,95 @@ | ||
| --- | ||
| title: Apollo compiler plugins | ||
| --- | ||
|
|
||
| The Apollo compiler supports [a wide range of options](../advanced/plugin-configuration). 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](../advanced/persisted-queries) ids registered on your backend. | ||
|
|
||
| The Apollo compiler use the [ServiceLoader API](https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html) 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: | ||
|
|
||
| ```kotlin | ||
| // 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.4") | ||
| } | ||
| ``` | ||
|
|
||
| Next create your plugin in a `src/main/kotlin/mypackage/MyPlugin` file: | ||
|
|
||
| ```kotlin | ||
| package mypackage | ||
|
|
||
| import com.apollographql.apollo3.compiler.OperationOutputGenerator | ||
| import com.apollographql.apollo3.compiler.Plugin | ||
| import com.apollographql.apollo3.compiler.operationoutput.OperationDescriptor | ||
| import com.apollographql.apollo3.compiler.operationoutput.OperationId | ||
|
|
||
| class MyPlugin: Plugin { | ||
| 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> { | ||
| // ... | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Make your plugin discoverable by [ServiceLoader](https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html) 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: | ||
|
|
||
| ``` | ||
| mypackage.MyPlugin | ||
| ``` | ||
|
|
||
| > [!NOTE] | ||
| > The name of the resource file is important. It must be `com.apollographql.apollo3.compiler.Plugin` 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: | ||
|
|
||
| ```kotlin | ||
| // 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")) // highlight-line | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| 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](https://www.apollographql.com/docs/kotlin/kdoc/apollo-compiler/com.apollographql.apollo3.compiler/-plugin/index.html) | ||
|
|
||
| For more examples, check out the [integration-tests](https://github.com/apollographql/apollo-kotlin/tree/main/tests/compiler-plugins). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.