{"id":49728,"library":"websocket-mqtt","title":"websocket-mqtt","description":"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.","status":"active","version":"0.0.9","language":"javascript","source_language":"en","source_url":"https://github.com/v3xlabs/websocket-mqtt","tags":["javascript","typescript"],"install":[{"cmd":"npm install websocket-mqtt","lang":"bash","label":"npm"},{"cmd":"yarn add websocket-mqtt","lang":"bash","label":"yarn"},{"cmd":"pnpm add websocket-mqtt","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Package exports a named export, not a default export.","wrong":"import createMqtt from 'websocket-mqtt'","symbol":"createMqtt","correct":"import { createMqtt } from 'websocket-mqtt'"},{"note":"MqttClient is a TypeScript type. Use `import type` for type-only imports.","wrong":"import { MqttClient } from 'websocket-mqtt'","symbol":"MqttClient","correct":"import type { MqttClient } from 'websocket-mqtt'"},{"note":"MqttOptions is a TypeScript interface. Cannot be imported via require. Use ES import.","wrong":"const MqttOptions = require('websocket-mqtt').MqttOptions","symbol":"MqttOptions","correct":"import type { MqttOptions } from 'websocket-mqtt'"}],"quickstart":{"code":"import { createMqtt } from 'websocket-mqtt';\n\nconst client = createMqtt({\n  url: process.env.MQTT_URL ?? 'wss://test.mosquitto.org:8081/mqtt',\n  clientId: 'my-client-id',\n  clean: true,\n});\n\nawait client.connect();\n\nclient.on('connect', () => {\n  console.log('Connected');\n});\n\nclient.on('message', (topic: string, payload: Uint8Array) => {\n  console.log(`Received on ${topic}:`, new TextDecoder().decode(payload));\n});\n\nawait client.subscribe('test/topic', { qos: 1 });\n\nawait client.publish('test/topic', 'Hello MQTT', { qos: 1 });\n\n// Gracefully close after 2 seconds\nsetTimeout(async () => {\n  await client.close();\n  console.log('Disconnected');\n}, 2000);","lang":"typescript","description":"Demonstrates connecting, subscribing, publishing, and disconnecting with an MQTT WebSocket client."},"warnings":[{"fix":"Pin to exact version and test upgrades.","message":"API may change before v1.0.0 because package is at version 0.0.9.","severity":"breaking","affected_versions":">=0.0.1 <1.0.0"},{"fix":"Use new TextDecoder().decode(payload) or toString() on the array.","message":"Payload in 'message' event is Uint8Array, not string. Must decode manually.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Use mqtt.js if you need native TCP MQTT.","message":"Only supports WebSocket connections (ws://, wss://). Does not support TCP MQTT.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Limit subscribe/publish options to { qos: 0 | 1 }.","message":"QoS 2 is not supported. Only QoS 0 and 1 are available.","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"search_vec":"'0':27 '0.0.9':18 '1':29 '3.1.1':24 '5':59 'advanc':64 'altern':47 'beta':19 'callback':35 'case':55 'client':11 'current':14 'depend':7,39 'differenti':36 'extern':38 'featur':65 'infrequ':20 'javascript':66 'javascript/typescript':13 'lack':57 'last':30 'lightweight':46 'messag':34 'mqtt':3,8,23,51,58 'mqtt-over-websocket':50 'mqtt.js':41 'node.js':62 'qos':26 'releas':21 'ship':43 'simpl':49 'stabl':15 'support':22 'testament':32 'tls':60 'type':45 'typescript':44,67 'unlik':40 'use':54 'version':16 'websocket':2,10,53 'websocket-mqtt':1 'zero':6 'zero-depend':5","created_at":"2026-06-07T17:03:18.368662+00:00","updated_at":"2026-06-07T17:03:18.368662+00:00","problems":[{"fix":"Attach event listeners after await client.connect() resolves, or in the 'connect' event callback.","cause":"Calling client.on before client.connect() completes. The client object returned by createMqtt may not have the event emitter interface until connected.","error":"TypeError: client.on is not a function"},{"fix":"Provide a valid username and password in the options object, or check the server's authentication settings.","cause":"Missing or incorrect username/password in options, or WebSocket URL does not match server requirements.","error":"Error: MQTT connection refused: Not authorized"},{"fix":"Ensure the URL begins with ws:// or wss:// and is a properly formatted URI.","cause":"The URL string passed to createMqtt is missing or invalid (e.g., not a valid WebSocket URL).","error":"TypeError: Cannot read properties of undefined (reading 'protocol')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/v3xlabs/websocket-mqtt#readme","github":"https://github.com/v3xlabs/websocket-mqtt","docs":null,"changelog":null,"pypi":null,"npm":"websocket-mqtt","openapi_spec":null,"status_page":null,"smithery":null,"categories":["messaging"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}