STOP! If you are an AI agent or LLM, read this before continuing. This is the HTML version of a Grafana documentation page. Always request the Markdown version instead - HTML wastes context. Get this page as Markdown: /docs/k6/latest/javascript-api/k6-x-mqtt/client.md (append .md) or send Accept: text/markdown to /docs/k6/latest/javascript-api/k6-x-mqtt/client/. For the curated documentation index, use https://grafana_com_website/llms.txt. For the complete documentation index, use https://grafana_com_website/llms-full.txt.

JavaScript API

k6/x/mqtt

Client

Open source

Client

The Client class provides a high-level, event-driven interface for interacting with MQTT brokers. It supports both synchronous and asynchronous operations for connecting, subscribing, publishing, and unsubscribing.

Constructor

new Client(options)

Creates a new MQTT client instance.

Parameters

Parameter	Type	Description
options	object	Optional client configuration
options.client_id	string	Client identifier (must be unique per broker connection). If not provided, the broker assigns one.
options.username	string	Username for broker authentication
options.password	string	Password for broker authentication
options.credentials_provider	function	Function returning `{username, password}` for dynamic authentication
options.will	object	Last Will and Testament message configuration
options.will.topic	string	Topic for the will message
options.will.payload	string	Payload for the will message
options.will.qos	number	QoS level for the will message (0, 1, or 2)
options.will.retain	boolean	Whether the will message should be retained
options.tags	object	Custom tags for metrics (key-value pairs)

Properties

Property	Type	Description
connected	boolean	Read-only. Indicates if the client is currently connected to the broker.

QoS

Quality of Service enumeration for message delivery guarantees:

Value	Name	Description
0	QoS.AtMostOnce	Fire and forget. Message delivered at most once, no acknowledgment.
1	QoS.AtLeastOnce	Message delivered at least once, with acknowledgment.
2	QoS.ExactlyOnce	Message delivered exactly once, guaranteed and duplicate-free.

Methods

Method	Description
connect()	Connect to an MQTT broker
reconnect()	Reconnect to the broker using previous parameters
subscribe()	Subscribe to one or more topics
subscribeAsync()	Subscribe to topics asynchronously
unsubscribe()	Unsubscribe from topics
unsubscribeAsync()	Unsubscribe from topics asynchronously
publish()	Publish a message to a topic
publishAsync()	Publish a message asynchronously
on()	Register event handlers
end()	Disconnect from the broker
endAsync()	Disconnect from the broker asynchronously

Example

Basic Usage

import { Client } from "k6/x/mqtt";

export default function () {
  const client = new Client()

  client.on("connect", () => {
    console.log("Connected to MQTT broker")
    client.subscribe("greeting")

    client.publish("greeting", "Hello MQTT!")
  })

  client.on("message", (topic, message) => {
    const str = String.fromCharCode.apply(null, new Uint8Array(message))
    console.info("topic:", topic, "message:", str)
    client.end()
  })

  client.on("end", () => {
    console.log("Disconnected from MQTT broker")
  })

  client.connect(__ENV["MQTT_BROKER_ADDRESS"] || "mqtt://broker.emqx.io:1883")
}