|
| 1 | +//// |
| 2 | +This document is maintained in the main Quarkus repository |
| 3 | +and pull requests should be submitted there: |
| 4 | +https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc |
| 5 | +//// |
| 6 | +[id="extensions-faq"] |
| 7 | += Frequently asked questions about writing extensions |
| 8 | +include::_attributes.adoc[] |
| 9 | +:diataxis-type: howto |
| 10 | +:categories: extensions |
| 11 | +//// |
| 12 | +:extension-status: preview |
| 13 | +TODO: uncomment the above for experimental or tech-preview content. |
| 14 | +The document header ends at the first blank line. Do not remove the blank line between the header and the abstract summary. |
| 15 | +//// |
| 16 | + |
| 17 | +## Should you write an extension? |
| 18 | + |
| 19 | +### Why would I want to write an extension? |
| 20 | + |
| 21 | +See the xref:writing-extensions#extension-philosophy[extension philosophy]. |
| 22 | + |
| 23 | +One useful thing extensions can do is bundle other extensions. |
| 24 | +Have a look at the link:https://quarkus.io/extensions/io.quarkiverse.microprofile/quarkus-microprofile/[Quarkus MicroProfile extension] for an example of aggregator extensions. |
| 25 | + |
| 26 | +### Are there cases an extension isn't necessary? |
| 27 | + |
| 28 | +Not every problem needs an extension! |
| 29 | + If you're just bundling up external libraries (that aren't already extensions) and making minor adjustments, you might not need an extension. |
| 30 | + For example, plain libraries can create new configuration elements and register classes with Jandex (this link:https://www.loicmathieu.fr/wordpress/en/informatique/quarkus-tip-comment-ne-pas-creer-une-extension-quarkus/[blog shows how]). |
| 31 | + |
| 32 | + |
| 33 | +## Bytecode transformation |
| 34 | + |
| 35 | +### How can I change the code of things on the classpath? |
| 36 | + |
| 37 | +A `BytecodeTransformerBuildItem` can be used to manipulate bytecode. |
| 38 | +For example, see this link:https://quarkus.io/blog/solving-problems-with-extensions/[blog about removed problematic bridge methods from a dependency]. |
| 39 | + |
| 40 | +## CDI |
| 41 | + |
| 42 | +### I'm working with CDI, and I don't know how to ... |
| 43 | + |
| 44 | +The xref:cdi-integration.adoc[CDI integration guide] presents solutions to a number of CDI-related use cases for extension authors. |
| 45 | + |
| 46 | +### I have transformed a user class to add an injected field, but CDI isn't working |
| 47 | + |
| 48 | +What happens if an extension transforms a user class using `BytecodeTransformerBuildItem`, and replaces `@jakarta.annotation.Resource` with `@jakarta.inject.Inject`? The field will not be injected by Arc. |
| 49 | +Debugging will show the transformed class being loaded in the app, but it looks like Arc doesn't see the new code. |
| 50 | + |
| 51 | +Arc-related transformations should generally be done with link:https://github.com/quarkusio/quarkus/blob/main/extensions/arc/deployment/src/main/java/io/quarkus/arc/deployment/AnnotationsTransformerBuildItem.java[AnnotationsTransformerBuildItem]. |
| 52 | +The reason is that _all_ Quarkus's bytecode transformations are done after Jandex indexing. This means changes are never reflected back in Jandex. |
| 53 | + |
| 54 | +Most extensions use Jandex as a source of truth to find out what to do. Those extensions won't see new/modified endpoints in the bytecode itself. |
| 55 | +The solution to this limitation is annotation transformers. You should also be aware that while Arc and Quarkus REST honour annotation transformers, not all extensions do. |
| 56 | + |
| 57 | +### Something in my classpath has @Inject annotations, which are confusing CDI. How can I fix that? |
| 58 | + |
| 59 | +You will need to implement an `AnnotationsTransformer` and strip out out the problematic injection sites. (Remember, if the use case involves CDI, it needs to be an `AnnotationsTransformer`, not a BytecodeTransformer`.) See link:https://quarkus.io/blog/solving-problems-with-extensions-2/[this blog] about on using an `AnnotationsTransformer` extension to clean non `@Inject` annotations from the Airline library so that it can be used in CDI-enabled runtimes. |
| 60 | + |
| 61 | +## Cross-cutting concerns |
| 62 | + |
| 63 | +### How can I redirect application logging to an external service? |
| 64 | + |
| 65 | +A `LogHandlerBuildItem` is a convenient way to redirect application logs. See this link:https://quarkus.io/blog/quarkus-aws-cloudwatch_extension/[worked example of an extension which directs output to AWS CloudWatch]. |
| 66 | + |
| 67 | +## Build and hosting infrastructure for extensions |
| 68 | + |
| 69 | +### Can I use Gradle to build my extension? |
| 70 | + |
| 71 | +Yes, but it's not the most typical pattern. |
| 72 | +See the xref:building-my-first-extension.adoc#gradle-setup[Building Your First Extension Guide] for instructions on setting up a Gradle extension. Have a look at the link:https://quarkus.io/extensions/org.jobrunr/quarkus-jobrunr/[JobRunr extension] for an example implementation. |
| 73 | + |
| 74 | +### If I want my extension to be in code.quarkus.io, does it have to be in the Quarkiverse GitHub org? |
| 75 | + |
| 76 | +Registering an extension in the catalog is independent from where the source code is. |
| 77 | +The link:https://hub.quarkiverse.io[quarkiverse repository] has some shortcuts to make releasing and testing extensions easier, but any extension can link:https://hub.quarkiverse.io/checklistfornewprojects/#make-your-extension-available-in-the-tooling[register into the catalog]. |
| 78 | + |
| 79 | +### My extension isn't showing up on extensions.quarkus.io |
| 80 | + |
| 81 | +Every extension in the link:https://github.com/quarkusio/quarkus-extension-catalog/tree/main/extensions[extension catalog] should appear in http://code.quarkus.io, http://extensions.quarkus.io, and the command line tools. |
| 82 | +The web pages at http://extensions.quarkus.io are refreshed a few times a delay, so there may be a delay in new extensions showing up there. |
| 83 | +To debug a missing extension, first: |
| 84 | + |
| 85 | +- Check your extension is present in link:https://central.sonatype.com/[Maven Central] |
| 86 | +- Check the extension is included the link:https://github.com/quarkusio/quarkus-extension-catalog/tree/main/extensions[extensions catalog list] (it only needs to be included once, and future versions will be automatically detected) |
| 87 | +- Check if the extension is listed in the http://https://registry.quarkus.io/q/swagger-ui/#/Client/get_client_extensions_all[Quarkus registry] list of all known extensions |
| 88 | +- Check if there has been a green link:https://github.com/quarkusio/extensions/actions/workflows/build_and_publish.yml[build of the extensions site] since updating the catalog |
| 89 | +
|
| 90 | +## Other topics |
| 91 | + |
| 92 | + |
| 93 | +### What's the difference between a quickstart and a codestart? |
| 94 | + |
| 95 | +Both codestarts and quickstarts are designed to help users get coding quickly. |
| 96 | +A codestarts is a generated application and a quickstart is browsable source code. |
| 97 | +Codestarts allow the creation of customised apps, which makes them quite powerful. |
0 commit comments