MQTT no navegador com JavaScript puro (sem build)

Você não precisa de npm, React nem bundler para falar MQTT em uma página web. O MQTT.js 5 já vem com um bundle pronto para o navegador: adicione uma tag <script>, chame mqtt.connect('wss://…') e a página publica e assina via WebSockets seguros. Este guia monta um cliente completo em um único arquivo, que você pode abrir direto do disco, subir em qualquer hospedagem estática ou colar em uma ferramenta interna.

Por que navegadores precisam de WebSockets

Navegadores não abrem sockets TCP diretos, então mqtt://host:1883 e mqtts://host:8883 estão fora do alcance de uma página web. Os brokers resolvem isso com um listener WebSocket: os mesmos pacotes MQTT trafegam dentro de frames WebSocket. Para broker.connectmq.com os endpoints são:

O caminho /mqtt faz diferença: conectar na porta certa com o caminho errado costuma falhar durante o upgrade HTTP (veja erro 404 no caminho do WebSocket). MQTT sobre WebSockets explica o transporte em detalhes.

A página completa

Salve isto como index.html. Ele fixa uma versão exata do MQTT.js no CDN, que expõe um objeto global mqtt.

<!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>

Abra o arquivo, digite uma mensagem e clique em Publish: a página assina o próprio topic aleatório, então a mensagem volta pelo broker e aparece no log. Cada aba ganha seu próprio topic e client ID, então duas abas abertas não interferem uma na outra. Para ver o tráfego de fora, abra o cliente MQTT online, assine testmqtt/browser-demo/# e publique de qualquer um dos lados.

Variante com módulos ES

Se você prefere módulos, o MQTT.js também publica um build ESM. Nenhuma variável global é criada, então você o importa:

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

Scripts de módulo são adiados automaticamente e não vazam variáveis para window. Alguns navegadores bloqueiam scripts de módulo em páginas abertas via file://, então sirva a pasta com um servidor web local:

python3 -m http.server 8000
# depois abra http://localhost:8000/

Opções que importam no navegador

Gere IDs com um prefixo que você reconheça nos logs do broker, ou use o gerador de client ID. Se precisar da mesma configuração em outra linguagem, o gerador de código MQTT produz trechos equivalentes.

Credenciais em uma página estática

Tudo em um arquivo HTML é público: qualquer pessoa pode ver o código-fonte e copiar username e password. Trate as credenciais do navegador de acordo:

• Crie um usuário de broker dedicado à página e restrinja-o com ACLs exatamente aos topics de que ela precisa. Um dashboard geralmente só precisa de leitura em .../telemetry/#.
• Nunca reutilize no navegador uma conta de dispositivo, de backend ou de administrador.
• Para usuários logados, deixe o backend emitir credenciais por usuário ou de curta duração após a autenticação e passe-as para mqtt.connect.

Autenticação MQTT via WebSocket no navegador detalha esses padrões.

Depurando a conexão

Abra as DevTools (F12) e confira dois lugares:

1. Console. Aqui aparecem os erros do evento error e as mensagens de WebSocket do próprio navegador.
2. Network → WS. Selecione a conexão para ver o upgrade HTTP (status 101 Switching Protocols quando dá certo) e os frames MQTT binários na aba Messages.

A consulta de reason codes traduz os códigos numéricos que brokers MQTT 5 retornam. Para descartar de vez a sua página, teste a mesma URL no cliente online: se conectar lá, o problema está no seu código, não no broker nem na rede.

Veja o topic da página demo no cliente online

Próximos passos

A página acima é um cliente completo. Os próximos passos típicos são uma interface de chat (um topic por sala, presença com Last Will), um gráfico ao vivo alimentado por telemetria de sensores ou um painel de controle que publica comandos. Quando o código passar de algumas centenas de linhas, migrar para o pacote npm e um bundler é fácil: a API mqtt.connect é idêntica, e é por isso que o guia do MQTT.js vale sem alterações.

Uma tag script, uma URL wss:// e alguns handlers de eventos são tudo de que um navegador precisa para falar MQTT. Fixe a versão da biblioteca, dê a cada aba seu próprio client ID, envie ao navegador apenas uma conta restrita e verifique cada mudança nas DevTools e no cliente online antes do deploy.

Perguntas frequentes