creating-extensions - SKILL.md Agent Skill

name: creating-extensions description: > How to create a new Quarkus extension: full module layout, package naming, artifact naming, dependency rules, and Dev UI setup.

Creating Extensions

Extension Module Layout

Every extension lives under extensions/<name>/ with this structure:

extensions/<name>/
  runtime/          # Runtime classes, recorders, beans (quarkus-<name>)
  runtime-api/      # (optional) Public APIs for loose coupling (quarkus-<name>-api)
  deployment/       # @BuildStep processors (quarkus-<name>-deployment)
  deployment-spi/   # (optional) Public build items for cross-extension use (quarkus-<name>-deployment-spi)
  runtime-dev/      # (optional) Dev UI/Shell components, dev mode only (quarkus-<name>-dev)
  codegen/          # (optional) Code generation utilities (quarkus-<name>-codegen)
  cli/              # (optional) CLI commands (quarkus-<name>-cli)
  codestart/        # (optional) Codestart templates (quarkus-<name>-codestart)

Only runtime and deployment are mandatory.

Dependency Rules

Deployment depends on runtime, never the reverse
External consumers use runtime-api or deployment-spi for loose coupling
External consumers use runtime or deployment for tight coupling
Both runtime/ and deployment/ POMs must include quarkus-extension-processor as an annotation processor path

Package Naming

Module	Package
Runtime	`io.quarkus.<extension-name>`
Runtime internals	`io.quarkus.<extension-name>.runtime.internal`
Runtime API	`io.quarkus.<extension-name>.api`
Deployment	`io.quarkus.<extension-name>.deployment`
Deployment SPI	`io.quarkus.<extension-name>.deployment.spi`
Runtime Dev	`io.quarkus.<extension-name>.dev`

Hyphenated names become underscored: quarkus-foo-bar -> io.quarkus.foo_bar

Artifact Naming

Runtime: quarkus-<name>
Deployment: quarkus-<name>-deployment
See adr/0009-extension-structure.adoc for the full naming table

Dev UI

Provide CardPageBuildItem and JsonRPCProvidersBuildItem in deployment processors guarded by @BuildSteps(onlyIf = IsLocalDevelopment.class)
Dev-only classes go in runtime-dev/ modules
See the classloading-and-runtime-dev skill for runtime-dev wiring details

After Creating an Extension

Run ./update-extension-dependencies.sh after adding/removing/renaming — this ensures modules like devtools/bom-descriptor-json build in the correct order relative to the new extension
Always install (not just compile) so dependent modules can find it
If you change a runtime module, rebuild its deployment module too
Run mvn -Dowasp-check in the extension directory to check for known security vulnerabilities in dependencies

External Maven Repositories

Quarkus uses --ignore-transitive-repositories to ensure all dependencies come from Maven Central. If your extension needs an external repository:

Discuss with the Quarkus Core team first — external repos are avoided
Add the repository to the specific extension module's pom.xml, not the root pom.xml
Declare Maven Central first in the <repositories> element
Add a .mvn/rrf/groupId-<REPOSITORY-ID>.txt file listing authorized groupIds (one per line)
Verify with: ./mvnw -Dquickly -Dmaven.repo.local=/tmp/temp-repo

Independent Projects

Some sub-projects in independent-projects/ have their own build lifecycle:

arc/ — The CDI implementation
resteasy-reactive/ — RESTEasy Reactive
qute/ — The templating engine
tools/ — Shared tooling utilities

These can be built standalone but are also included in the main Quarkus build.