MQTT.js Documentation

MQTT.js supports both CommonJS require and ES6 import syntax.

CommonJS

const mqtt = require("mqtt");
const client = mqtt.connect("mqtt://test.mosquitto.org");

ES6 Modules

Default import

import mqtt from "mqtt";
let client = mqtt.connect("mqtt://test.mosquitto.org");

Individual component import

import { connect } from "mqtt";
let client = connect("mqtt://test.mosquitto.org");

To use MQTT.js in Ali Mini Programs, use the alis protocol.

const mqtt = require("mqtt");
const client = mqtt.connect("alis://test.mosquitto.org");

MQTT.js is compatible with bundlers like Webpack, Vite, and React.

For versions > 5.2.0, you can use a standard import which your bundler will handle automatically:

import mqtt from 'mqtt'

If you need to target a specific bundle from the dist folder, use the following paths:

• mqtt/dist/mqtt (IIFE, unminified)
• mqtt/dist/mqtt.min (IIFE, minified)
• mqtt/dist/mqtt.esm (ESM, minified)

import mqtt from 'mqtt'

// Or specific bundles:
import * as mqtt from 'mqtt/dist/mqtt'
import * as mqtt from 'mqtt/dist/mqtt.min'
import mqtt from 'mqtt/dist/mqtt.esm'

You can run the full test suite (both browser and node tests) using the standard test command. To run specific individual tests, you can invoke the node test runner directly with esbuild-register.

npm test

# Example: Running a specific test file
node -r esbuild-register --test test/keepaliveManager.ts

The MQTT.js CLI allows you to interact with an MQTT broker directly from your terminal. You can publish messages, subscribe to topics, and check the version of the installed package.

Available commands:

• publish: Publish a message to the broker.
• subscribe: Subscribe to updates from the broker.
• version: Display the current MQTT.js version.
• help: Show help information about commands.

To get detailed information about a specific command, use mqtt help [command].

To use MQTT.js in WeChat Mini Programs, use the wxs protocol. You must also include polyfills for AbortController and navigator before importing mqtt.

import 'abortcontroller-polyfill/dist/abortcontroller-polyfill-only'
import 'esbuild-plugin-polyfill-node/polyfills/navigator'
const mqtt = require("mqtt");

const client = mqtt.connect("wxs://test.mosquitto.org", {
  timerVariant: 'native'
});

Node.js tests utilize the native NodeJS Test Runner. Tests are located in the test directory, with runTests.ts serving as the entrypoint for filtering and concurrency management.

You can run tests in watch mode, inspect them via debugger, or filter them using the --test-name-pattern flag.

To use MQTT.js in your project, install the mqtt package using npm:

npm install mqtt --save

Browser tests are executed using wtr (Web Test Runner). The environment starts a local broker using aedes-cli with ws and wss support and runs tests across Chrome, Firefox, and Safari.

Note: You must run npm run build before running browser tests because they use the bundled version of the library. To enable debugging, set sourcemap: true in esbuild.js before building.

For interactive debugging, you can run wtr in manual mode to select tests via a browser UI at localhost:8001.

npm run test:browser

# Run in manual mode for interactive selection and debugging
npx wtr --manual --open

There are two ways to trigger a new release:

1. Locally: Run npm run release and follow the interactive CLI instructions.
2. GitHub: Manually trigger the release workflow via GitHub Actions, specifying the desired release type.

To run the linter and automatically fix fixable issues in the codebase, use the lint-fix command.

npm run lint-fix

When using MQTT.js in a browser environment, you must use MQTT over WebSockets. This means your connection strings must use the ws:// or wss:// protocols.

Important Limitations:

• The wsOption configuration is not supported in browsers.
• Due to browser security restrictions, client.on('error') may not catch all connection-time errors, as browsers often report connection errors in an indistinguishable way.