@capgo/capacitor-mqtt

Why MQTT?

MQTT (Message Queuing Telemetry Transport) is a lightweight, publish-subscribe messaging protocol ideal for:

• IoT devices - Low bandwidth, minimal battery usage.
• Real-time messaging - Instant message delivery between clients
• Remote monitoring - Send/receive data from distributed devices
• Home automation - Connect smart devices seamlessly

This plugin provides a complete MQTT client implementation for Capacitor apps, supporting both Android and iOS.

This plugin is compatible with Capacitor 8 and above.

PR's are greatly appreciated.

Features

• Connect to MQTT brokers via TCP
• Subscribe to topics with QoS support
• Publish messages with QoS and retained flag options
• Listen for incoming messages
• Automatic reconnection support
• Connection loss detection
• Clean session management
• Keep-alive interval configuration

Installation

npm install @capgo/capacitor-mqtt
npx cap sync

Usage

Connect to MQTT Broker

import { MqttBridge } from '@capgo/capacitor-mqtt';

const connectionOptions = {
  serverURI: 'tcp://broker.hivemq.com',
  port: 1883,
  clientId: 'my-client-id',
  username: '',
  password: '',
  setCleanSession: true,
  connectionTimeout: 30,
  keepAliveInterval: 60,
  setAutomaticReconnect: true,
};

await MqttBridge.connect(connectionOptions);

Subscribe to Topic

const result = await MqttBridge.subscribe({
  topic: 'my/topic',
  qos: 0,
});

Publish Message

const result = await MqttBridge.publish({
  topic: 'my/topic',
  payload: 'Hello World',
  qos: 0,
  retained: false,
});

Listen for Messages

import { MqttBridge } from '@capgo/capacitor-mqtt';

MqttBridge.addListener('onMessageArrived', (result) => {
  console.log('Topic:', result.topic);
  console.log('Message:', result.message);
});

Disconnect

await MqttBridge.disconnect();

API

• connect(...)
• disconnect()
• subscribe(...)
• publish(...)
• addListener('onConnectionLost', ...)
• addListener('onConnectComplete', ...)
• addListener('onMessageArrived', ...)
• Interfaces
• Type Aliases

connect(...)

connect(options: { serverURI: string; port: number; clientId: string; username: string; password: string; setCleanSession: boolean; connectionTimeout: number; keepAliveInterval: number; setAutomaticReconnect: boolean; setLastWill?: { willTopic: string; willPayload: string; willQoS: number; setRetained: boolean; }; }) => Promise<any>

| Param | Type | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | options | { serverURI: string; port: number; clientId: string; username: string; password: string; setCleanSession: boolean; connectionTimeout: number; keepAliveInterval: number; setAutomaticReconnect: boolean; setLastWill?: { willTopic: string; willPayload: string; willQoS: number; setRetained: boolean; }; } |

Returns: Promise<any>

disconnect()

disconnect() => Promise<any>

Returns: Promise<any>

subscribe(...)

subscribe(options: { topic: string; qos: number; }) => Promise<{ topic: string; qos: number; }>

| Param | Type | | ------------- | -------------------------------------------- | | options | { topic: string; qos: number; } |

Returns: Promise<{ topic: string; qos: number; }>

publish(...)

publish(options: { topic: string; payload: string; qos: number; retained: boolean; }) => Promise<{ topic: string; payload: string; qos: number; retained: boolean; messageId: any; }>

| Param | Type | | ------------- | -------------------------------------------------------------------------------- | | options | { topic: string; payload: string; qos: number; retained: boolean; } |

Returns: Promise<{ topic: string; payload: string; qos: number; retained: boolean; messageId: any; }>

addListener('onConnectionLost', ...)

addListener(eventName: 'onConnectionLost', listener: onConnectionLostListener) => Promise<PluginListenerHandle>

| Param | Type | | --------------- | ----------------------------------------------------------------------------- | | eventName | 'onConnectionLost' | | listener | onConnectionLostListener |

Returns: Promise<PluginListenerHandle>

addListener('onConnectComplete', ...)

addListener(eventName: 'onConnectComplete', listener: onConnectCompleteListener) => Promise<PluginListenerHandle>

| Param | Type | | --------------- | ------------------------------------------------------------------------------- | | eventName | 'onConnectComplete' | | listener | onConnectCompleteListener |

Returns: Promise<PluginListenerHandle>

addListener('onMessageArrived', ...)

addListener(eventName: 'onMessageArrived', listener: onMessageArrivedListener) => Promise<PluginListenerHandle>

| Param | Type | | --------------- | ----------------------------------------------------------------------------- | | eventName | 'onMessageArrived' | | listener | onMessageArrivedListener |

Returns: Promise<PluginListenerHandle>

Interfaces

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

Type Aliases

onConnectionLostListener

(x: { connectionStatus: string; reasonCode: number; message: string; }): void

onConnectCompleteListener

(x: { reconnected: boolean; serverURI: string; }): void

onMessageArrivedListener

(x: { topic: string; message: string; }): void

License

MPL-2.0