The mqtt npm package is a client library for the MQTT protocol, which is a lightweight messaging protocol designed for small sensors and mobile devices. It allows you to connect to an MQTT broker, publish messages to topics, and subscribe to topics to receive messages.
Connect to an MQTT broker
This feature allows you to connect to an MQTT broker. The code sample demonstrates how to connect to a public MQTT broker (HiveMQ) and log a message upon successful connection.
const mqtt = require('mqtt');
const client = mqtt.connect('mqtt://broker.hivemq.com');
client.on('connect', () => {
console.log('Connected to broker');
});Publish messages to a topic
This feature allows you to publish messages to a specific topic. The code sample shows how to publish a message 'Hello MQTT' to the topic 'test/topic' after connecting to the broker.
const mqtt = require('mqtt');
const client = mqtt.connect('mqtt://broker.hivemq.com');
client.on('connect', () => {
client.publish('test/topic', 'Hello MQTT');
console.log('Message published');
});Subscribe to a topic
This feature allows you to subscribe to a specific topic and receive messages published to that topic. The code sample demonstrates subscribing to 'test/topic' and logging any received messages.
const mqtt = require('mqtt');
const client = mqtt.connect('mqtt://broker.hivemq.com');
client.on('connect', () => {
client.subscribe('test/topic', (err) => {
if (!err) {
console.log('Subscribed to topic');
}
});
});
client.on('message', (topic, message) => {
console.log(`Received message: ${message.toString()} on topic: ${topic}`);
});mqttjs is another popular MQTT client library for Node.js. It offers similar functionalities to the mqtt package, including connecting to brokers, publishing, and subscribing to topics. It is known for its simplicity and ease of use.
aedes is a barebone MQTT broker that can be embedded in Node.js applications. While it serves as a broker rather than a client, it can be used in conjunction with mqtt to create a complete MQTT solution. It is lightweight and highly performant.
mosca is an MQTT broker that can be used with Node.js. It is designed to be fast and scalable, making it suitable for IoT applications. Like aedes, it can be used alongside mqtt to provide a full MQTT ecosystem.
MQTT.js is a client library for the MQTT protocol, written in JavaScript for node.js and the browser.
MQTT.js is an OPEN Open Source Project, see the Contributing section to find out what this means.
v5.0.0 (07/2023)
MqttClient instance new is now required.v4.0.0 (Released 04/2020) removes support for all end of life node versions, and now supports node v12 and v14. It also adds improvements to debug logging, along with some feature additions.
As a breaking change, by default a error handler is built into the MQTT.js client, so if any
errors are emitted and the user has not created an event handler on the client for errors, the client will
not break as a result of unhandled errors. Additionally, typical TLS errors like ECONNREFUSED, ECONNRESET have been
added to a list of TLS errors that will be emitted from the MQTT.js client, and so can be handled as connection errors.
v3.0.0 adds support for MQTT 5, support for node v10.x, and many fixes to improve reliability.
Note: MQTT v5 support is experimental as it has not been implemented by brokers yet.
v2.0.0 removes support for node v0.8, v0.10 and v0.12, and it is 3x faster in sending
packets. It also removes all the deprecated functionality in v1.0.0,
mainly mqtt.createConnection and mqtt.Server. From v2.0.0,
subscriptions are restored upon reconnection if clean: true.
v1.x.x is now in LTS, and it will keep being supported as long as
there are v0.8, v0.10 and v0.12 users.
As a breaking change, the encoding option in the old client is
removed, and now everything is UTF-8 with the exception of the
password in the CONNECT message and payload in the PUBLISH message,
which are Buffer.
Another breaking change is that MQTT.js now defaults to MQTT v3.1.1, so to support old brokers, please read the client options doc.
v1.0.0 improves the overall architecture of the project, which is now split into three components: MQTT.js keeps the Client, mqtt-connection includes the barebone Connection code for server-side usage, and mqtt-packet includes the protocol parser and generator. The new Client improves performance by a 30% factor, embeds Websocket support (MOWS is now deprecated), and it has a better support for QoS 1 and 2. The previous API is still supported but deprecated, as such, it is not documented in this README.
npm install mqtt --save
For the sake of simplicity, let's put the subscriber and the publisher in the same file:
const mqtt = require("mqtt");
const client = mqtt.connect("mqtt://test.mosquitto.org");
client.on("connect", () => {
client.subscribe("presence", (err) => {
if (!err) {
client.publish("presence", "Hello mqtt");
}
});
});
client.on("message", (topic, message) => {
// message is Buffer
console.log(message.toString());
client.end();
});
output:
Hello mqtt
If you want to run your own MQTT broker, you can use Mosquitto or Aedes-cli, and launch it.
You can also use a test instance: test.mosquitto.org.
If you do not want to install a separate broker, you can try using the Aedes.
const mqtt = require("mqtt") // require mqtt
const client = mqtt.connect("mqtt://test.mosquitto.org") // create a client
import mqtt from "mqtt"; // import namespace "mqtt"
let client = mqtt.connect("mqtt://test.mosquitto.org"); // create a client
import { connect } from "mqtt"; // import connect from mqtt
let client = connect("mqtt://test.mosquitto.org"); // create a client
MQTT.js bundles a command to interact with a broker. In order to have it available on your path, you should install MQTT.js globally:
npm install mqtt -g
Then, on one terminal
mqtt sub -t 'hello' -h 'test.mosquitto.org' -v
On another
mqtt pub -t 'hello' -h 'test.mosquitto.org' -m 'from MQTT.js'
See mqtt help <command> for the command help.
MQTT.js uses the debug package for debugging purposes. To enable debug logs, add the following environment variable on runtime :
# (example using PowerShell, the VS Code default)
$env:DEBUG='mqttjs*'
An important part of any websocket connection is what to do when a connection drops off and the client needs to reconnect. MQTT has built-in reconnection support that can be configured to behave in ways that suit the application.
transformWsUrl (Websocket Only)When an mqtt connection drops and needs to reconnect, it's common to require that any authentication associated with the connection is kept current with the underlying auth mechanism. For instance some applications may pass an auth token with connection options on the initial connection, while other cloud services may require a url be signed with each connection.
By the time the reconnect happens in the application lifecycle, the original auth data may have expired.
To address this we can use a hook called transformWsUrl to manipulate
either of the connection url or the client options at the time of a reconnect.
Example (update clientId & username on each reconnect):
const transformWsUrl = (url, options, client) => {
client.options.username = `token=${this.get_current_auth_token()}`;
client.options.clientId = `${this.get_updated_clientId()}`;
return `${this.get_signed_cloud_url(url)}`;
}
const connection = await mqtt.connectAsync(<wss url>, {
...,
transformWsUrl: transformUrl,
});
Now every time a new WebSocket connection is opened (hopefully not too often), we will get a fresh signed url or fresh auth token data.
Note: Currently this hook does not support promises, meaning that in order to use the latest auth token, you must have some outside mechanism running that handles application-level authentication refreshing so that the websocket connection can simply grab the latest valid token or signed url.
createWebsocket (Websocket Only)When you need to add a custom websocket subprotocol or header to open a connection through a proxy with custom authentication this callback allows you to create your own instance of a websocket which will be used in the mqtt client.
const createWebsocket = (url, websocketSubProtocols, options) => {
const subProtocols = [
websocketSubProtocols[0],
'myCustomSubprotocolOrOAuthToken',
]
return new WebSocket(url, subProtocols)
}
const client = await mqtt.connectAsync(<wss url>, {
...,
createWebsocket: createWebsocket,
});
reconnectPeriod optionTo ensure that the mqtt client automatically tries to reconnect when the
connection is dropped, you must set the client option reconnectPeriod to a
value greater than 0. A value of 0 will disable reconnection and then terminate
the final connection when it drops.
The default value is 1000 ms which means it will try to reconnect 1 second after losing the connection.
If the client sets the option autoUseTopicAlias:true then MQTT.js uses existing topic alias automatically.
example scenario:
1. PUBLISH topic:'t1', ta:1 (register)
2. PUBLISH topic:'t1' -> topic:'', ta:1 (auto use existing map entry)
3. PUBLISH topic:'t2', ta:1 (register overwrite)
4. PUBLISH topic:'t2' -> topic:'', ta:1 (auto use existing map entry based on the receent map)
5. PUBLISH topic:'t1' (t1 is no longer mapped to ta:1)
User doesn't need to manage which topic is mapped to which topic alias. If the user want to register topic alias, then publish topic with topic alias. If the user want to use topic alias, then publish topic without topic alias. If there is a mapped topic alias then added it as a property and update the topic to empty string.
If the client sets the option autoAssignTopicAlias:true then MQTT.js uses existing topic alias automatically.
If no topic alias exists, then assign a new vacant topic alias automatically. If topic alias is fully used, then LRU(Least Recently Used) topic-alias entry is overwritten.
example scenario:
The broker returns CONNACK (TopicAliasMaximum:3)
1. PUBLISH topic:'t1' -> 't1', ta:1 (auto assign t1:1 and register)
2. PUBLISH topic:'t1' -> '' , ta:1 (auto use existing map entry)
3. PUBLISH topic:'t2' -> 't2', ta:2 (auto assign t1:2 and register. 2 was vacant)
4. PUBLISH topic:'t3' -> 't3', ta:3 (auto assign t1:3 and register. 3 was vacant)
5. PUBLISH topic:'t4' -> 't4', ta:1 (LRU entry is overwritten)
Also user can manually register topic-alias pair using PUBLISH topic:'some', ta:X. It works well with automatic topic alias assign.
mqtt.connect()mqtt.connectAsync()mqtt.Client()mqtt.Client#connect()mqtt.Client#publish()mqtt.Client#publishAsync()mqtt.Client#subscribe()mqtt.Client#subscribeAsync()mqtt.Client#unsubscribe()mqtt.Client#unsubscribeAsync()mqtt.Client#end()mqtt.Client#endAsync()mqtt.Client#removeOutgoingMessage()mqtt.Client#reconnect()mqtt.Client#handleMessage()mqtt.Client#connectedmqtt.Client#reconnectingmqtt.Client#getLastMessageId()mqtt.Store()mqtt.Store#put()mqtt.Store#del()mqtt.Store#createStream()mqtt.Store#close()Connects to the broker specified by the given url and options and returns a Client.
The URL can be on the following protocols: 'mqtt', 'mqtts', 'tcp',
'tls', 'ws', 'wss', 'wxs', 'alis'. The URL can also be an object as returned by
URL.parse(),
in that case the two objects are merged, i.e. you can pass a single
object with both the URL and the connect options.
You can also specify a servers options with content: [{ host: 'localhost', port: 1883 }, ... ], in that case that array is iterated
at every connect.
For all MQTT-related options, see the Client constructor.
Asynchronous wrapper around the connect function.
Returns a Promise that resolves to a mqtt.Client instance when the client
fires a 'connect' or 'end' event, or rejects with an error if the 'error'
is fired.
Note that the manualConnect option will cause the promise returned by this
function to never resolve or reject as the underlying client never fires any
events.
The Client class wraps a client connection to an
MQTT broker over an arbitrary transport method (TCP, TLS,
WebSocket, ecc).
Client is an EventEmitter that has it's own events
Client automatically handles the following:
The arguments are:
streamBuilder is a function that returns a subclass of the Stream class that supports
the connect event. Typically a net.Socket.options is the client connection options (see: the connect packet). Defaults:
wsOptions: is the WebSocket connection options. Default is {}.
It's specific for WebSockets. For possible options have a look at: https://github.com/websockets/ws/blob/master/doc/ws.md.
keepalive: 60 seconds, set to 0 to disable
reschedulePings: reschedule ping messages after sending packets (default true)
clientId: 'mqttjs_' + Math.random().toString(16).substr(2, 8)
protocolId: 'MQTT'
protocolVersion: 4
clean: true, set to false to receive QoS 1 and 2 messages while
offline
reconnectPeriod: 1000 milliseconds, interval between two
reconnections. Disable auto reconnect by setting to 0.
connectTimeout: 30 * 1000 milliseconds, time to wait before a
CONNACK is received
username: the username required by your broker, if any
password: the password required by your broker, if any
incomingStore: a Store for the incoming packets
outgoingStore: a Store for the outgoing packets
queueQoSZero: if connection is broken, queue outgoing QoS zero messages (default true)
customHandleAcks: MQTT 5 feature of custom handling puback and pubrec packets. Its callback:
customHandleAcks: function(topic, message, packet, done) {/*some logic with calling done(error, reasonCode)*/}
autoUseTopicAlias: enabling automatic Topic Alias using functionality
autoAssignTopicAlias: enabling automatic Topic Alias assign functionality
properties: properties MQTT 5.0.
object that supports the following properties:
sessionExpiryInterval: representing the Session Expiry Interval in seconds number,receiveMaximum: representing the Receive Maximum value number,maximumPacketSize: representing the Maximum Packet Size the Client is willing to accept number,topicAliasMaximum: representing the Topic Alias Maximum value indicates the highest value that the Client will accept as a Topic Alias sent by the Server number,requestResponseInformation: The Client uses this value to request the Server to return Response Information in the CONNACK boolean,requestProblemInformation: The Client uses this value to indicate whether the Reason String or User Properties are sent in the case of failures boolean,userProperties: The User Property is allowed to appear multiple times to represent multiple name, value pairs object,authenticationMethod: the name of the authentication method used for extended authentication string,authenticationData: Binary Data containing authentication data binaryauthPacket: settings for auth packet object
will: a message that will sent by the broker automatically when
the client disconnect badly. The format is:
topic: the topic to publishpayload: the message to publishqos: the QoSretain: the retain flagproperties: properties of will by MQTT 5.0:
willDelayInterval: representing the Will Delay Interval in seconds number,payloadFormatIndicator: Will Message is UTF-8 Encoded Character Data or not boolean,messageExpiryInterval: value is the lifetime of the Will Message in seconds and is sent as the Publication Expiry Interval when the Server publishes the Will Message number,contentType: describing the content of the Will Message string,responseTopic: String which is used as the Topic Name for a response message string,correlationData: The Correlation Data is used by the sender of the Request Message to identify which request the Response Message is for when it is received binary,userProperties: The User Property is allowed to appear multiple times to represent multiple name, value pairs objecttransformWsUrl : optional (url, options, client) => url function
For ws/wss protocols only. Can be used to implement signing
urls which upon reconnect can have become expired.
createWebsocket : optional url, websocketSubProtocols, options) => Websocket function
For ws/wss protocols only. Can be used to implement a custom websocket subprotocol or implementation.
resubscribe : if connection is broken and reconnects,
subscribed topics are automatically subscribed again (default true)
messageIdProvider: custom messageId provider. when new UniqueMessageIdProvider() is set, then non conflict messageId is provided.
log: custom log function. Default uses debug package.
manualConnect: prevents the constructor to call connect. In this case after the mqtt.connect is called you should call client.connect manually.
timerVariant: defaults to auto, which tries to determine which timer is most appropriate for you environment, if you're having detection issues, you can set it to worker or native
In case mqtts (mqtt over tls) is required, the options object is passed through to tls.connect(). If using a self-signed certificate, set rejectUnauthorized: false. However, be cautious as this exposes you to potential man in the middle attacks and isn't recommended for production.
For those supporting multiple TLS protocols on a single port, like MQTTS and MQTT over WSS, utilize the ALPNProtocols option. This lets you define the Application Layer Protocol Negotiation (ALPN) protocol. You can set ALPNProtocols as a string array, Buffer, or Uint8Array based on your setup.
If you are connecting to a broker that supports only MQTT 3.1 (not 3.1.1 compliant), you should pass these additional options:
{
protocolId: 'MQIsdp',
protocolVersion: 3
}
This is confirmed on RabbitMQ 3.2.4, and on Mosquitto < 1.3. Mosquitto version 1.3 and 1.4 works fine without those.
'connect'function (connack) {}
Emitted on successful (re)connection (i.e. connack rc=0).
connack received connack packet. When clean connection option is false and server has a previous session
for clientId connection option, then connack.sessionPresent flag is true. When that is the case,
you may rely on stored session and prefer not to send subscribe commands for the client.'reconnect'function () {}
Emitted when a reconnect starts.
'close'function () {}
Emitted after a disconnection.
'disconnect'function (packet) {}
Emitted after receiving disconnect packet from broker. MQTT 5.0 feature.
'offline'function () {}
Emitted when the client goes offline.
'error'function (error) {}
Emitted when the client cannot connect (i.e. connack rc != 0) or when a parsing error occurs.
The following TLS errors will be emitted as an error event:
ECONNREFUSEDECONNRESETEADDRINUSEENOTFOUND'end'function () {}
Emitted when mqtt.Client#end() is called.
If a callback was passed to mqtt.Client#end(), this event is emitted once the
callback returns.
'message'function (topic, message, packet) {}
Emitted when the client receives a publish packet
topic topic of the received packetmessage payload of the received packetpacket received packet, as defined in
mqtt-packet'packetsend'function (packet) {}
Emitted when the client sends any packet. This includes .published() packets as well as packets used by MQTT for managing subscriptions and connections
packet received packet, as defined in
mqtt-packet'packetreceive'function (packet) {}
Emitted when the client receives any packet. This includes packets from subscribed topics as well as packets used by MQTT for managing subscriptions and connections
packet received packet, as defined in
mqtt-packetBy default client connects when constructor is called. To prevent this you can set manualConnect option to true and call client.connect() manually.
Publish a message to a topic
topic is the topic to publish to, Stringmessage is the message to publish, Buffer or Stringoptions is the options to publish with, including:
qos QoS level, Number, default 0retain retain flag, Boolean, default falsedup mark as duplicate flag, Boolean, default falseproperties: MQTT 5.0 properties object
payloadFormatIndicator: Payload is UTF-8 Encoded Character Data or not boolean,messageExpiryInterval: the lifetime of the Application Message in seconds number,topicAlias: value that is used to identify the Topic instead of using the Topic Name number,responseTopic: String which is used as the Topic Name for a response message string,correlationData: used by the sender of the Request Message to identify which request the Response Message is for when it is received binary,userProperties: The User Property is allowed to appear multiple times to represent multiple name, value pairs object,subscriptionIdentifier: representing the identifier of the subscription number,contentType: String describing the content of the Application Message stringcbStorePut - function (), fired when message is put into outgoingStore if QoS is 1 or 2.callback - function (err), fired when the QoS handling completes,
or at the next tick if QoS 0. An error occurs if client is disconnecting.Async publish. Returns a Promise<void>.
Subscribe to a topic or topics
topic is a String topic to subscribe to or an Array of
topics to subscribe to. It can also be an object, it has as object
keys the topic name and as value the QoS, like {'test1': {qos: 0}, 'test2': {qos: 1}}.
MQTT topic wildcard characters are supported (+ - for single level and # - for multi level)options is the options to subscribe with, including:
qos QoS subscription level, default 0nl No Local MQTT 5.0 flag (If the value is true, Application Messages MUST NOT be forwarded to a connection with a ClientID equal to the ClientID of the publishing connection)rap Retain as Published MQTT 5.0 flag (If true, Application Messages forwarded using this subscription keep the RETAIN flag they were published with. If false, Application Messages forwarded using this subscription have the RETAIN flag set to 0.)rh Retain Handling MQTT 5.0 (This option specifies whether retained messages are sent when the subscription is established.)properties: object
subscriptionIdentifier: representing the identifier of the subscription number,userProperties: The User Property is allowed to appear multiple times to represent multiple name, value pairs objectcallback - function (err, granted)
callback fired on suback where:
err a subscription error or an error that occurs when client is disconnectinggranted is an array of {topic, qos} where:
topic is a subscribed to topicqos is the granted QoS level on itAsync subscribe. Returns a Promise<granted[]>.
Unsubscribe from a topic or topics
topic is a String topic or an array of topics to unsubscribe fromoptions: options of unsubscribe.
properties: object
userProperties: The User Property is allowed to appear multiple times to represent multiple name, value pairs objectcallback - function (err), fired on unsuback. An error occurs if client is disconnecting.Async unsubscribe. Returns a Promise<void>.
Close the client, accepts the following options:
force: passing it to true will close the client right away, without
waiting for the in-flight messages to be acked. This parameter is
optional.options: options of disconnect.
reasonCode: Disconnect Reason Code numberproperties: object
sessionExpiryInterval: representing the Session Expiry Interval in seconds number,reasonString: representing the reason for the disconnect string,userProperties: The User Property is allowed to appear multiple times to represent multiple name, value pairs object,serverReference: String which can be used by the Client to identify another Server to use stringcallback: will be called when the client is closed. This parameter is
optional.Async end. Returns a Promise<void>.
Remove a message from the outgoingStore. The outgoing callback will be called with Error('Message removed') if the message is removed.
After this function is called, the messageId is released and becomes reusable.
mId: The messageId of the message in the outgoingStore.Connect again using the same options as connect()
Handle messages with backpressure support, one at a time.
Override at will, but always call callback, or the client
will hang.
Boolean : set to true if the client is connected. false otherwise.
Number : get last message id. This is for sent messages only.
Boolean : set to true if the client is trying to reconnect to the server. false otherwise.
In-memory implementation of the message store.
options is the store options:
clean: true, clean inflight messages when close is called (default true)Other implementations of mqtt.Store:
Adds a packet to the store, a packet is
anything that has a messageId property.
The callback is called when the packet has been stored.
Creates a stream with all the packets in the store.
Removes a packet from the store, a packet is
anything that has a messageId property.
The callback is called when the packet has been removed.
Closes the Store.
[!IMPORTANT] The only protocol supported in browsers is MQTT over WebSockets, so you must use
ws://orwss://protocols.
While the ws module is used in NodeJS, WebSocket is used in browsers. This is totally transparent to users except for the following:
The wsOption is not supported in browsers.
Browsers doesn't allow to catch many WebSocket errors for security reasons as:
Access to this information could allow a malicious Web page to gain information about your network, so they require browsers report all connection-time errors in an indistinguishable way.
So listening for client.on('error') may not catch all the errors you would get in NodeJS env.
MQTT.js is bundled using esbuild. It is tested working with all bundlers like Webpack, Vite and React.
You can find all mqtt bundles versions in dist folder:
mqtt.js - iife format, not minifiedmqtt.min.js - iife format, minifiedmqtt.esm.js - esm format minifiedStarting from MQTT.js > 5.2.0 you can import mqtt in your code like this:
import mqtt from 'mqtt'
This will be automatically handled by your bundler.
Otherwise you can choose to use a specific bundle like:
import * as mqtt from 'mqtt/dist/mqtt'
import * as mqtt from 'mqtt/dist/mqtt.min'
import mqtt from 'mqtt/dist/mqtt.esm'
The MQTT.js bundle is available through http://unpkg.com, specifically at https://unpkg.com/mqtt/dist/mqtt.min.js. See http://unpkg.com for the full documentation on version ranges.
Here is how QoS works:
About data consumption, obviously, QoS 2 > QoS 1 > QoS 0, if that's a concern to you.
Starting from v5 this project is written in TypeScript and the type definitions are included in the package.
Example:
import { connect } from "mqtt"
const client = connect('mqtt://test.mosquitto.org')
Supports WeChat Mini Program. Use the wxs protocol. See the WeChat docs.
const mqtt = require("mqtt");
const client = mqtt.connect("wxs://test.mosquitto.org");
Supports Ali Mini Program. Use the alis protocol. See the Alipay docs.
const mqtt = require("mqtt");
const client = mqtt.connect("alis://test.mosquitto.org");
MQTT.js is an OPEN Open Source Project. This means that:
Individuals making significant and valuable contributions are given commit-access to the project to contribute as they see fit. This project is more like an open wiki than a standard guarded open source project.
See the CONTRIBUTING.md file for more details.
MQTT.js is only possible due to the excellent work of the following contributors:
| Name | GitHub | |
|---|---|---|
| Adam Rudd | GitHub/adamvr | Twitter/@adam_vr |
| Matteo Collina | GitHub/mcollina | Twitter/@matteocollina |
| Maxime Agor | GitHub/4rzael | Twitter/@4rzael |
| Siarhei Buntsevich | GitHub/scarry1992 | |
| Daniel Lando | GitHub/robertsLando |
If you would like to support MQTT.js, please consider sponsoring the author and active maintainers:
MIT
FAQs
A library for the MQTT protocol
We found that mqtt demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 7 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.