By Version

Quarkus Extension Metadata

Quarkus extensions are distributed as Maven JAR artifacts that application and other libraries may depend on. When a Quarkus application project is built, tested or edited using the Quarkus dev tools, Quarkus extension JAR artifacts will be identified on the application classpath by the presence of the Quarkus extension metadata files in them. This document describes the purpose of each Quarkus extension metadata file and its content.

META-INF/quarkus-extension.yaml

Every runtime extension artifact must include this file. This file is used by Quarkus dev tools when displaying information about an extension, creating a new project or adding extensions to an existing project, etc. This file isn’t used at application build or bootstrap times. The basic and required metadata included in this file can be generated by the Quarkus Maven and Gradle plugins when the extension artifact is built. However, typically, extension authors will want to provide more information about the extension to the Quarkus dev tools and users. The extra information could be provided in a template META-INF/quarkus-extension.yaml found in the extension runtime module’s resources directory, e.g. src/main/resources/META-INF/quarkus-extension.yaml. Here is an example of such a template for the quarkus-resteasy-reactive extension:

name: "RESTEasy Reactive" (1)
artifact: ${project.groupId}:${project.artifactId}:${project.version} (2)
metadata:
  short-name: "resteasy-reactive" (3)
  keywords: (4)
  - "jaxrs"
  - "web"
  - "rest"
  categories: (5)
  - "web"
  - "reactive"
  status: "stable" (6)
  guide: "https://quarkus.io/guides/resteasy-reactive" (7)
  icon-url: "https://quarkus.io/assets/images/about/icon-reactive.svg" (8)
  codestart: (9)
    name: "resteasy-reactive"
    languages:
      - "java"
      - "kotlin"
      - "scala"
    artifact: "io.quarkus:quarkus-project-core-extension-codestarts"
  config: (10)
  - "quarkus.resteasy-reactive."

1	Extension name displayed to users
2	Extension runtime artifact expression that will be replaced with the actual coordinates during the build, this field could be omitted
3	Short name that could be used to quickly locate an extension in the catalog of extensions provided by the dev tools to the users
4	Keywords that can be used to search for extensions in the extension catalog provided by the dev tools to the users
5	Categories the extension should appear under on code.quarkus.io. This field can be omitted, the extension will still be listed on code.quarkus.io but won’t be categorized
6	Maturity status that could be `stable`, `preview`, `experimental`. It is up to extension maintainers to evaluate the maturity status and communicate it to the users
7	Link to the extension guide or documentation page
8	Link to an externally hosted image. This is used in the Quarkus dev tools as the extension icon. It should be square, and any resolution greater than 220 pixels. Supported formats are png, jpeg, tiff, webp, and svg. Alternatively, if you set the social media preview on the extension’s source code repository, the tools will pick up that image.
9	Codestart information
10	Configuration prefix

And here is the final version of the file included in the runtime JAR augmented with other information collected by the Quarkus Maven plugin:

name: "RESTEasy Reactive"
artifact: "io.quarkus:quarkus-resteasy-reactive:999-SNAPSHOT"
metadata:
  short-name: "resteasy-reactive"
  keywords:
  - "jaxrs"
  - "web"
  - "rest"
  categories:
  - "web"
  - "reactive"
  status: "stable"
  guide: "https://quarkus.io/guides/resteasy-reactive"
  codestart:
    name: "resteasy-reactive"
    languages:
    - "java"
    - "kotlin"
    - "scala"
    artifact: "io.quarkus:quarkus-project-core-extension-codestarts::jar:999-SNAPSHOT"
  config:
  - "quarkus.resteasy-reactive."
  built-with-quarkus-core: "999-SNAPSHOT" (1)
  capabilities: (2)
    provides:
    - "io.quarkus.rest"
    - "io.quarkus.resteasy.reactive"
  extension-dependencies: (3)
  - "io.quarkus:quarkus-resteasy-reactive-common"
  - "io.quarkus:quarkus-mutiny"
  - "io.quarkus:quarkus-smallrye-context-propagation"
  - "io.quarkus:quarkus-vertx"
  - "io.quarkus:quarkus-arc"
  - "io.quarkus:quarkus-netty"
  - "io.quarkus:quarkus-vertx-http"
  - "io.quarkus:quarkus-core"
  - "io.quarkus:quarkus-jsonp"
description: "A Jakarta REST implementation utilizing build time processing and Vert.x.\
  \ This extension is not compatible with the quarkus-resteasy extension, or any of\
  \ the extensions that depend on it." (4)
scm:
  url: "https://github.com/quarkusio/quarkus" (5)
sponsor: A Sponsoring Organisation (6)

1	Quarkus version the extension was built with
2	Capabilities this extension provides
3	Direct dependencies on other extensions
4	Description that can be displayed to users. In this case, the description was copied from the `pom.xml` of the extension module but it could also be provided in the template file.
5	The source code repository of this extension. Optional, and will often be set automatically. In GitHub Actions builds, it will be inferred from the CI environment. For other GitHub repositories, it can be controlled by setting a `GITHUB_REPOSITORY` environment variable.
6	The sponsor(s) of this extension. Optional, and will sometimes be determined automatically from commit history.

META-INF/quarkus-extension.properties

Every runtime extension artifact must include this file. This file is read by the Quarkus bootstrap mechanism and is meant to contain only the information that is relevant for building or bootstrapping an applications. This file is typically generated by the corresponding Quarkus Maven or Gradle plugin when the extension project is built and shouldn’t be edited manually. The following properties may appear in this file:

Name Presence Description

Name	Presence	Description
`deployment-artifact`	Required	Points to the corresponding extension deployment artifact in the `groupId:artifactId[:classifier:type]:version` format
`parent-first-artifacts`	Optional	Comma-separated list of artifact keys (`groupId:artifactId:classifier:type`) that are to be loaded in a parent first manner. This can be used to work around issues where a given class needs to be loaded by the system ClassLoader.
`runner-parent-first-artifacts`	Optional	Comma-separated list of artifact keys that are to be loaded in a parent first manner in addition to those configured with `parent-first-artifacts` when an application is launched from a production binary package. This can be used to work around issues where a given class needs to be loaded by the system ClassLoader.
`excluded-artifacts`	Optional	Comma-separated list of artifact keys that will never be loaded by the class loader, and will not be packed into the final application.
`lesser-priority-artifacts`	Optional	Comma-separated list of artifact keys that will only be used to load a class or resource if no other artifact containing that class or resource exists. This is used in order to control the order of artifacts when multiple contain the same classes.
`removed-resources.*`	Optional	Resources that should be removed/hidden from dependencies. This allows for classes and other resources to be removed from dependencies, so they are not accessible to the application. This is a map of artifact key to a comma-separated list of resources to be removed. When running in dev and test mode these resources are hidden from the ClassLoader, when running in production mode these files are removed from the jars that contain them. Note that if you want to remove a class you need to specify the class file name. e.g. to remove com.acme.Foo you would specify com/acme/Foo.class.
`provides-capabilities`	Optional	List of capabilities this extension provides
`requires-capabilities`	Optional	List of capabilities this extension requires to be provided by other Quarkus extensions
`conditional-dependencies`	Optional	List of conditional dependencies this extension declares
`dependency-condition`	Optional	Dependency condition that has to be satisfied for a conditional dependency on this extension to be activated

deployment-artifact

Required

Points to the corresponding extension deployment artifact in the groupId:artifactId[:classifier:type]:version format

parent-first-artifacts

Optional

Comma-separated list of artifact keys (groupId:artifactId:classifier:type) that are to be loaded in a parent first manner. This can be used to work around issues where a given class needs to be loaded by the system ClassLoader.

runner-parent-first-artifacts

Optional

Comma-separated list of artifact keys that are to be loaded in a parent first manner in addition to those configured with parent-first-artifacts when an application is launched from a production binary package. This can be used to work around issues where a given class needs to be loaded by the system ClassLoader.

excluded-artifacts

Optional

Comma-separated list of artifact keys that will never be loaded by the class loader, and will not be packed into the final application.

lesser-priority-artifacts

Optional

Comma-separated list of artifact keys that will only be used to load a class or resource if no other artifact containing that class or resource exists. This is used in order to control the order of artifacts when multiple contain the same classes.

removed-resources.*

Optional

Resources that should be removed/hidden from dependencies. This allows for classes and other resources to be removed from dependencies, so they are not accessible to the application. This is a map of artifact key to a comma-separated list of resources to be removed. When running in dev and test mode these resources are hidden from the ClassLoader, when running in production mode these files are removed from the jars that contain them. Note that if you want to remove a class you need to specify the class file name. e.g. to remove com.acme.Foo you would specify com/acme/Foo.class.

provides-capabilities

Optional

List of capabilities this extension provides

requires-capabilities

Optional

List of capabilities this extension requires to be provided by other Quarkus extensions

conditional-dependencies

Optional

List of conditional dependencies this extension declares

dependency-condition

Optional

Dependency condition that has to be satisfied for a conditional dependency on this extension to be activated

META-INF/quarkus-config-roots.list

This file may appear in a runtime extension artifact as well as in a deployment one. This file must not be edited manually, it is generated as part of the extension project build process and contains a list of Java class names that are annotated with io.quarkus.runtime.annotations.ConfigRoot an extension provides.

META-INF/quarkus-javadoc.properties

Same as quarkus-config-roots.list, this file may appear in a runtime extension artifact as well in a deployment one. It is generated as part of the extension project build process from the descriptions of configuration options available in the classes annotated with io.quarkus.runtime.annotations.ConfigRoot and is not supported to be edited manually.

META-INF/quarkus-build-steps.list

This file may appear in a deployment extension artifact. It contains a list of classes that implement Quarkus build steps (methods annotated with io.quarkus.deployment.annotations.BuildStep). This file is generated as part of the extension project build process and must not be edited manually.

META-INF/quarkus-extension.yaml
META-INF/quarkus-extension.properties
META-INF/quarkus-config-roots.list
META-INF/quarkus-javadoc.properties
META-INF/quarkus-build-steps.list

Quarkus Extension Metadata

META-INF/quarkus-extension.yaml

META-INF/quarkus-extension.properties

META-INF/quarkus-config-roots.list

META-INF/quarkus-javadoc.properties

META-INF/quarkus-build-steps.list

Related content

On the same topics