websocket-mqtt

library0.0.9jsnpmunverified

A zero-dependency MQTT over WebSocket client for JavaScript/TypeScript. Current stable version is 0.0.9 (beta, infrequent releases). Supports MQTT 3.1.1 with QoS 0 and 1, last will testament, and message callbacks. Differentiator: no external dependencies unlike mqtt.js, and ships TypeScript types. Lightweight alternative for simple MQTT-over-WebSocket use cases, but lacks MQTT 5, TLS in Node.js, and advanced features.

messaging

npm install websocket-mqtt

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WEBSOCKET-MQTT

websocket-mqtt

messagingjavascriptv0.0.9

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createMqtt

✓ import { createMqtt } from 'websocket-mqtt'

✗ import createMqtt from 'websocket-mqtt'

Package exports a named export, not a default export.

MqttClient

✓ import type { MqttClient } from 'websocket-mqtt'

✗ import { MqttClient } from 'websocket-mqtt'

MqttClient is a TypeScript type. Use `import type` for type-only imports.

MqttOptions

✓ import type { MqttOptions } from 'websocket-mqtt'

✗ const MqttOptions = require('websocket-mqtt').MqttOptions

MqttOptions is a TypeScript interface. Cannot be imported via require. Use ES import.

Demonstrates connecting, subscribing, publishing, and disconnecting with an MQTT WebSocket client.

import { createMqtt } from 'websocket-mqtt'; const client = createMqtt({ url: process.env.MQTT_URL ?? 'wss://test.mosquitto.org:8081/mqtt', clientId: 'my-client-id', clean: true, }); await client.connect(); client.on('connect', () => { console.log('Connected'); }); client.on('message', (topic: string, payload: Uint8Array) => { console.log(`Received on ${topic}:`, new TextDecoder().decode(payload)); }); await client.subscribe('test/topic', { qos: 1 }); await client.publish('test/topic', 'Hello MQTT', { qos: 1 }); // Gracefully close after 2 seconds setTimeout(async () => { await client.close(); console.log('Disconnected'); }, 2000);

Debug

Known issues

breakingAPI may change before v1.0.0 because package is at version 0.0.9.

fix

Pin to exact version and test upgrades.

affects: >=0.0.1 <1.0.0

gotchaPayload in 'message' event is Uint8Array, not string. Must decode manually.

fix

Use new TextDecoder().decode(payload) or toString() on the array.

affects: >=0.0.1

gotchaOnly supports WebSocket connections (ws://, wss://). Does not support TCP MQTT.

fix

Use mqtt.js if you need native TCP MQTT.

affects: >=0.0.1

gotchaQoS 2 is not supported. Only QoS 0 and 1 are available.

fix

Limit subscribe/publish options to { qos: 0 | 1 }.

affects: >=0.0.1

Errors

Common errors & fixes

TypeError: client.on is not a function

Calling client.on before client.connect() completes. The client object returned by createMqtt may not have the event emitter interface until connected.

fix

Attach event listeners after await client.connect() resolves, or in the 'connect' event callback.

Error: MQTT connection refused: Not authorized

Missing or incorrect username/password in options, or WebSocket URL does not match server requirements.

fix

Provide a valid username and password in the options object, or check the server's authentication settings.

TypeError: Cannot read properties of undefined (reading 'protocol')

The URL string passed to createMqtt is missing or invalid (e.g., not a valid WebSocket URL).

fix

Ensure the URL begins with ws:// or wss:// and is a properly formatted URI.

Upgrade

Version history

0.0.9latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

22 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/v3xlabs/websocket-mqtt ↗

packagewebsocket-mqtt ↗

homepagehttps://github.com/v3xlabs/websocket-mqtt#readme ↗