Installation

Requirements

Maven 3.8.1+
JDK 17+ with JAVA_HOME configured appropriately
A running MQTT broker — or nothing at all in dev/test mode, where Dev Services starts one for you

Add the extension

Add the io.quarkiverse.hivemqclient:quarkus-hivemq-client extension to your build file:

<dependency>
    <groupId>io.quarkiverse.hivemqclient</groupId>
    <artifactId>quarkus-hivemq-client</artifactId>
    <version>2.5.1</version>
</dependency>

You also need the SmallRye Reactive Messaging MQTT connector, which provides the base MQTT API:

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-smallrye-reactive-messaging-mqtt</artifactId>
</dependency>

Alternatively, add both from the command line:

./mvnw quarkus:add-extension -Dextensions="hivemq,smallrye-reactive-messaging-mqtt"

Create an application from scratch

You can bootstrap a project that already wires the HiveMQ connector using the extension’s codestart:

mvn io.quarkus:quarkus-maven-plugin:3.37.1:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=hivemq-quickstart \
    -DclassName="org.acme.quickstart.GreetingResource" \
    -Dextensions="rest,hivemq,smallrye-reactive-messaging-mqtt"

cd hivemq-quickstart

Then run it in dev mode — a broker is provided automatically by Dev Services:

./mvnw quarkus:dev

Compatibility

This extension tracks specific Quarkus and HiveMQ client versions. Check the Compatibility Matrix to pick the version that matches your Quarkus platform.

Next steps

Usage — configure channels and write your first producer/consumer
Security & TLS — connect to a secured broker