MQTT im Browser mit reinem JavaScript (ohne Build-Schritt)

Du brauchst weder npm noch React noch einen Bundler, um aus einer Webseite heraus MQTT zu sprechen. MQTT.js 5 bringt ein fertiges Browser-Bundle mit: ein <script>-Tag einfügen, mqtt.connect('wss://…') aufrufen, und die Seite publisht und abonniert über sichere WebSockets. Dieser Guide baut einen vollständigen Client in einer einzigen Datei, die du direkt von der Festplatte öffnen, auf jeden statischen Host legen oder in ein internes Tool einfügen kannst.

Warum Browser WebSockets brauchen

Browser können keine rohen TCP-Sockets öffnen, deshalb sind mqtt://host:1883 und mqtts://host:8883 für eine Webseite unerreichbar. Broker lösen das mit einem WebSocket-Listener: Dieselben MQTT-Pakete reisen in WebSocket-Frames. Für broker.connectmq.com sind die Endpoints:

Der Pfad /mqtt ist wichtig: Wer den richtigen Port mit dem falschen Pfad anspricht, scheitert meist schon beim HTTP-Upgrade (siehe WebSocket-Pfad 404). MQTT über WebSockets erklärt den Transport im Detail.

Die komplette Seite

Speichere das als index.html. Die Seite pinnt eine exakte MQTT.js-Version vom CDN, die ein globales mqtt-Objekt bereitstellt.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>MQTT browser client</title>
  <script src="https://unpkg.com/mqtt@5.10.1/dist/mqtt.min.js"></script>
  <style>
    body { font: 15px/1.5 system-ui, sans-serif; max-width: 640px; margin: 2rem auto; padding: 0 1rem; }
    #log { background: #111; color: #9f9; padding: .75rem; height: 260px; overflow: auto; font-family: monospace; }
    input, button { font: inherit; padding: .4rem .6rem; }
  </style>
</head>
<body>
  <h1>MQTT over WSS</h1>
  <p>Status: <strong id="status">connecting…</strong></p>
  <form id="pub">
    <input id="msg" placeholder="Message" required>
    <button>Publish</button>
  </form>
  <pre id="log"></pre>

  <script>
    const URL = 'wss://broker.connectmq.com:8084/mqtt';
    const TOPIC = 'testmqtt/browser-demo/' + Math.random().toString(16).slice(2, 8);

    const $ = (id) => document.getElementById(id);
    const log = (line) => {
      $('log').textContent += new Date().toLocaleTimeString() + '  ' + line + '\n';
      $('log').scrollTop = $('log').scrollHeight;
    };

    const client = mqtt.connect(URL, {
      clientId: 'web-' + Math.random().toString(16).slice(2, 10),
      // username: 'username', password: 'password',   // see "Credentials" below
      protocolVersion: 5,
      clean: true,
      keepalive: 30,
      connectTimeout: 10_000,
      reconnectPeriod: 2_000,
    });

    client.on('connect', () => {
      $('status').textContent = 'connected';
      client.subscribe(TOPIC, { qos: 1 }, (err) => {
        log(err ? 'subscribe failed: ' + err.message : 'subscribed to ' + TOPIC);
      });
    });

    client.on('message', (topic, payload) => {
      log(topic + '  ' + payload.toString());
    });

    client.on('reconnect', () => { $('status').textContent = 'reconnecting…'; });
    client.on('offline',   () => { $('status').textContent = 'offline'; });
    client.on('error',     (err) => log('error: ' + err.message));

    $('pub').addEventListener('submit', (e) => {
      e.preventDefault();
      client.publish(TOPIC, $('msg').value, { qos: 1 });
      $('msg').value = '';
    });

    window.addEventListener('pagehide', () => client.end());
  </script>
</body>
</html>

Öffne die Datei, tippe eine Nachricht und klick auf Publish: Die Seite abonniert ihr eigenes zufälliges Topic, also kommt die Nachricht über den Broker zurück und erscheint im Log. Jeder Tab bekommt ein eigenes Topic und eine eigene Client-ID, zwei offene Tabs stören sich also nicht. Um den Traffic von außen zu sehen, öffne den Online-MQTT-Client, abonniere testmqtt/browser-demo/# und publishe von einer der beiden Seiten.

ES-Modul-Variante

Wenn du Module bevorzugst: MQTT.js veröffentlicht auch einen ESM-Build. Es wird kein Global angelegt, du importierst ihn also:

<script type="module">
  import mqtt from 'https://unpkg.com/mqtt@5.10.1/dist/mqtt.esm.js';

  const client = mqtt.connect('wss://broker.connectmq.com:8084/mqtt', { protocolVersion: 5 });
  client.on('connect', () => client.publish('testmqtt/browser-demo/esm', 'hello from a module'));
</script>

Modul-Scripts werden automatisch verzögert ausgeführt und legen keine Variablen in window ab. Manche Browser blockieren Modul-Scripts auf Seiten, die über file:// geöffnet wurden. Liefere den Ordner deshalb über einen lokalen Webserver aus:

python3 -m http.server 8000
# dann http://localhost:8000/ öffnen

Optionen, die im Browser zählen

Erzeuge IDs mit einem Präfix, das du in den Broker-Logs wiedererkennst, oder nutze den Client-ID-Generator. Brauchst du dasselbe Setup in einer anderen Sprache, liefert der MQTT-Codegenerator entsprechende Snippets.

Zugangsdaten in einer statischen Seite

Alles in einer HTML-Datei ist öffentlich: Jeder kann sich den Quelltext ansehen und username und password kopieren. Behandle Browser-Zugangsdaten entsprechend:

• Leg einen eigenen Broker-Benutzer für die Seite an und beschränke ihn per ACL auf genau die Topics, die sie braucht. Ein Dashboard braucht meist nur Lesezugriff auf .../telemetry/#.
• Verwende im Browser niemals einen Geräte-, Backend- oder Admin-Account wieder.
• Für eingeloggte Nutzer lässt du dein Backend nach der Authentifizierung benutzerbezogene oder kurzlebige Zugangsdaten ausstellen und übergibst sie an mqtt.connect.

MQTT-WebSocket-Authentifizierung im Browser geht diese Muster im Detail durch.

Die Verbindung debuggen

Öffne die DevTools (F12) und schau an zwei Stellen nach:

1. Console. Hier erscheinen Fehler aus dem error-Event und die WebSocket-Meldungen des Browsers selbst.
2. Network → WS. Wähl die Verbindung aus, um das HTTP-Upgrade (Status 101 Switching Protocols bei Erfolg) und die binären MQTT-Frames im Tab Messages zu sehen.

Das Reason-Code-Nachschlagewerk übersetzt die numerischen Codes, die MQTT-5-Broker zurückgeben. Um deine Seite komplett auszuschließen, probier dieselbe URL im Online-Client: Verbindet er sich dort, liegt das Problem in deinem Code, nicht am Broker oder Netzwerk.

Topic der Demo-Seite im Online-Client ansehen

Wie es weitergeht

Die Seite oben ist ein vollständiger Client. Typische nächste Schritte sind eine Chat-Oberfläche (ein Topic pro Raum, Presence über Last Will), ein Live-Chart mit Sensor-Telemetrie oder ein Bedienpanel, das Befehle publisht. Wenn der Code über ein paar hundert Zeilen wächst, ist der Umstieg auf das npm-Paket und einen Bundler einfach: Die mqtt.connect-API ist identisch, weshalb der MQTT.js-Guide unverändert gilt.

Ein Script-Tag, eine wss://-URL und ein paar Event-Handler sind alles, was ein Browser für MQTT braucht. Pinne die Bibliotheksversion, gib jedem Tab eine eigene Client-ID, liefere nur einen eingeschränkten Account an den Browser aus und prüfe jede Änderung in den DevTools und im Online-Client, bevor du deployst.

Häufig gestellte Fragen