Nanoscale Parts Manufacturing

    TypeScript icon, indicating that this package has built-in type declarations

    2.13.2 • Public • Published

    This if a fork of the MQTT.js library with changes to enable it to work on React Native.

    Install (for React Native)

    1. Install this fork

      npm install rn-mqtt --save
    2. Install react-native-tcp

      npm install react-native-tcp --save
      react-native link react-native-tcp
    3. Add node-libs-browser

      npm install node-libs-browser --save-dev
    4. Enable react native packager to include the node-libs

      1. Add a file rn-cli.config.js to the root directory

        const extraNodeModules = require('node-libs-browser')
        // add any customisations = require.resolve('react-native-tcp') 
        module.exports = { 
      2. Add a globals.js file to the root directory

        global.Buffer = require('buffer').Buffer
        global.process = require('process')
        // Needed so that 'stream-http' chooses the right default protocol.
        global.location = {
          protocol: 'file:'
        // Some modules expect userAgent to be a string
        global.navigator.userAgent = 'React Native'
        // flag that we are running in react native
        global.process.reactNative = true
      3. Edit the and index.ios.js files to include the globals.js file

        // import this at the top
        import './globals'
        // import your app code after globals.js
        import './app/app'

    Known Issues

    • Only works for tcp connections. Doesn't work for websockets

    Original MQTT.js README


    Build Status codecov


    Sauce Test Status

    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.

    JavaScript StyleGuide

    Important notes for existing users

    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.

    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 id not documented in this README.

    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.


    npm install mqtt --save


    For the sake of simplicity, let's put the subscriber and the publisher in the same file:

    var mqtt = require('mqtt')
    var client  = mqtt.connect('mqtt://')
    client.on('connect', function () {
      client.publish('presence', 'Hello mqtt')
    client.on('message', function (topic, message) {
      // message is Buffer


    Hello mqtt

    If you want to run your own MQTT broker, you can use Mosquitto or Mosca, and launch it. You can also use a test instance: and are both public.

    If you do not want to install a separate broker, you can try using the mqtt-connection.

    to use MQTT.js in the browser see the browserify section

    Promise support

    If you want to use the new async-await functionality in JavaScript, or just prefer using Promises instead of callbacks, async-mqtt is a wrapper over MQTT.js which uses promises instead of callbacks when possible.

    Command Line Tools

    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 '' -v

    On another

    mqtt pub -t 'hello' -h '' -m 'from MQTT.js'

    See mqtt help <command> for the command help.


    mqtt.connect([url], options)

    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'. 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.

    mqtt.Client(streamBuilder, options)

    The Client class wraps a client connection to an MQTT broker over an arbitrary transport method (TCP, TLS, WebSocket, ecc).

    Client automatically handles the following:

    • Regular server pings
    • QoS flow
    • Automatic reconnections
    • Start publishing before being connected

    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:
      • 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
      • 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)
      • will: a message that will sent by the broker automatically when the client disconnect badly. The format is:
        • topic: the topic to publish
        • payload: the message to publish
        • qos: the QoS
        • retain: the retain flag
      • transformWsUrl : 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.
      • resubscribe : if connection is broken and reconnects, subscribed topics are automatically subscribed again (default true)

    In case mqtts (mqtt over tls) is required, the options object is passed through to tls.connect(). If you are using a self-signed certificate, pass the rejectUnauthorized: false option. Beware that you are exposing yourself to man in the middle attacks, so it is a configuration that is not recommended for production environments.

    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.

    Event '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.

    Event 'reconnect'

    function () {}

    Emitted when a reconnect starts.

    Event 'close'

    function () {}

    Emitted after a disconnection.

    Event 'offline'

    function () {}

    Emitted when the client goes offline.

    Event 'error'

    function (error) {}

    Emitted when the client cannot connect (i.e. connack rc != 0) or when a parsing error occurs.

    Event 'message'

    function (topic, message, packet) {}

    Emitted when the client receives a publish packet

    • topic topic of the received packet
    • message payload of the received packet
    • packet received packet, as defined in mqtt-packet

    Event '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

    Event '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

    mqtt.Client#publish(topic, message, [options], [callback])

    Publish a message to a topic

    • topic is the topic to publish to, String
    • message is the message to publish, Buffer or String
    • options is the options to publish with, including:
      • qos QoS level, Number, default 0
      • retain retain flag, Boolean, default false
      • dup mark as duplicate flag, Boolean, default false
    • callback - function (err), fired when the QoS handling completes, or at the next tick if QoS 0. An error occurs if client is disconnecting.

    mqtt.Client#subscribe(topic/topic array/topic object, [options], [callback])

    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': 0, 'test2': 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 0
    • callback - function (err, granted) callback fired on suback where:
      • err a subscription error or an error that occurs when client is disconnecting
      • granted is an array of {topic, qos} where:
        • topic is a subscribed to topic
        • qos is the granted qos level on it

    mqtt.Client#unsubscribe(topic/topic array, [callback])

    Unsubscribe from a topic or topics

    • topic is a String topic or an array of topics to unsubscribe from
    • callback - function (err), fired on unsuback. An error occurs if client is disconnecting.

    mqtt.Client#end([force], [cb])

    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.
    • cb: will be called when the client is closed. This parameter is optional.


    Remove a message from the outgoingStore. The outgoing callback will be called withe 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.

    mqtt.Client#handleMessage(packet, callback)

    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.

    Other implementations of mqtt.Store:

    mqtt.Store#put(packet, callback)

    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.

    mqtt.Store#del(packet, cb)

    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.


    Via CDN

    The MQTT.js bundle is available through, specifically at See for the full documentation on version ranges.

    Wexin App

    Surport Weixin App. See Doc.


    var mqtt = require('mqtt')
    var client  = mqtt.connect('wxs://')


    import { connect } from 'mqtt';
    const client  = connect('wxs://');


    In order to use MQTT.js as a browserify module you can either require it in your browserify bundles or build it as a stand alone module. The exported module is AMD/CommonJs compatible and it will add an object in the global space.

    npm install -g browserify // install browserify
    cd node_modules/mqtt
    npm install . // install dev dependencies
    browserify mqtt.js -s mqtt > browserMqtt.js // require mqtt in your client-side app


    Just like browserify, export MQTT.js as library. The exported module would be var mqtt = xxx and it will add an object in the global space. You could also export module in other formats (AMD/CommonJS/others) by setting output.libraryTarget in webpack configuration.

    npm install -g webpack // install webpack
    cd node_modules/mqtt
    npm install . // install dev dependencies
    webpack mqtt.js ./browserMqtt.js --output-library mqtt

    you can then use mqtt.js in the browser with the same api than node's one.

      <title>test Ws mqtt.js</title>
    <script src="./browserMqtt.js"></script>
      var client = mqtt.connect() // you add a ws:// url here
      client.on("message", function (topic, payload) {
        alert([topic, payload].join(""))
      client.publish("mqtt/demo", "hello world!")

    Your broker should accept websocket connection (see MQTT over Websockets to setup Mosca).

    Signed WebSocket Urls

    If you need to sign an url, for example for AWS IoT, then you can pass in a transformWsUrl function to the mqtt.connect() options This is needed because signed urls have an expiry and eventually upon reconnects, a new signed url needs to be created:

    // This module doesn't actually exist, just an example
    var awsIotUrlSigner = require('awsIotUrlSigner')
    mqtt.connect('wss://', {
      transformWsUrl: function (url, options, client) {
        // It's possible to inspect some state on options(pre parsed url components)
        // and the client (reconnect state etc)
        return awsIotUrlSigner(url)
    // Now every time a new WebSocket connection is opened (hopefully not that
    // often) we get a freshly signed url

    About QoS

    Here is how QoS works:

    • QoS 0 : received at most once : The packet is sent, and that's it. There is no validation about whether it has been received.
    • QoS 1 : received at least once : The packet is sent and stored as long as the client has not received a confirmation from the server. MQTT ensures that it will be received, but there can be duplicates.
    • QoS 2 : received exactly once : Same as QoS 1 but there is no duplicates.

    About data consumption, obviously, QoS 2 > QoS 1 > QoS 0, if that's a concern to you.

    Usage with TypeScript

    This repo bundles TypeScript definition files for use in TypeScript projects and to support tools that can read .d.ts files.


    Before you can begin using these TypeScript definitions with your project, you need to make sure your project meets a few of these requirements:

    • TypeScript >= 2.1
    • Set tsconfig.json: {"compilerOptions" : {"moduleResolution" : "node"}, ...}
    • Includes the TypeScript definitions for node. You can use npm to install this by typing the following into a terminal window: npm install --save-dev @types/node


    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 file for more details.


    MQTT.js is only possible due to the excellent work of the following contributors:

    Adam RuddGitHub/adamvrTwitter/@adam_vr
    Matteo CollinaGitHub/mcollinaTwitter/@matteocollina
    Maxime AgorGitHub/4rzaelTwitter/@4rzael




    npm i rn-mqtt

    DownloadsWeekly Downloads






    Last publish


    • nofarius