Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kaandesu/vue-paho-mqtt
Easy-to-use MQTT client for Vue 3 with centralized subscription management, type support, and built-in alert notifications.
https://github.com/kaandesu/vue-paho-mqtt
mqtt mqtt-client paho-mqtt plugin vue vue3-typescript
Last synced: about 9 hours ago
JSON representation
Easy-to-use MQTT client for Vue 3 with centralized subscription management, type support, and built-in alert notifications.
- Host: GitHub
- URL: https://github.com/kaandesu/vue-paho-mqtt
- Owner: kaandesu
- License: mit
- Created: 2023-03-29T16:05:53.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2024-07-21T18:43:10.000Z (2 months ago)
- Last Synced: 2024-09-18T16:41:20.108Z (9 days ago)
- Topics: mqtt, mqtt-client, paho-mqtt, plugin, vue, vue3-typescript
- Language: TypeScript
- Homepage: https://kaandesu.github.io/vue-paho-mqtt/
- Size: 1.07 MB
- Stars: 21
- Watchers: 4
- Forks: 3
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# Vue-Paho-Mqtt Plugin
The `vue-paho-mqtt` plugin provides a convenient way to use the [Eclipse Paho MQTT JavaScript client](https://www.eclipse.org/paho/clients/js/) with Vue 3.
This plugin allows you to connect to a MQTT broker and subscribe to topics in your Vue app. It uses [paho-mqtt](https://www.npmjs.com/package/paho-mqtt) to connect to the broker and provides several useful features such as auto-reconnect, message handlers, and error notifications.
[Live demo](https://kaandesu.github.io/vue-paho-mqtt)
## Table of contents
- [Installation](#installation)
- [Setup](#setup)
- [Vite / VueCLI](#vite--vuecli)
- [Quasar](#quasar-framework-quasar-boot)
- [Nuxt3](#nuxt3-nuxt-plugins)
- [Options](#options)
- [Plugin Options](#plugin-options)
- [MQTT Options](#mqtt-options)
- [MQTT Quality of Service (QoS) and Retention Options for Publish](#mqtt-quality-of-service-qos-and-retention-options-for-publish)
- [Notification Alerts](#notification-alerts)
- [Global MQTT client instance: $mqtt](#global-mqtt-client-instance-mqtt)
- [connect()](#connect)
- [disconnect()](#disconnect)
- [subscribe()](#subscribe)
- [publish()](#publish)
- [host()](#host)
- [port()](#port)
- [path()](#path)
- [username()](#username)
- [password()](#password)
- [clientId()](#client-id)
- [mainTopic()](#main-topic)
- [unsubscribe()](#unsubscribe)
- [unsubscribeAll()](#unsubscribe-all)
- [status()](#status)
- [Usage Example](#usage-example)
- [Vue Options API](#vue-options-api)
- [Vue Composition API](#vue-composition-api)
- [Contributing](#contributing)
- [License](#license)
- [Credits](#credits)
- [Contact](#contact)
- [Changelog](#changelog)
- [Security](#security)
## Installation
Install the package using npm:
```bash
npm install vue-paho-mqtt
```
---
## Setup
To use the plugin, you need to create an instance of it and pass it to the `use` function:
### Vite / VueCLI
```typescript
// src/main.ts
import App from './App.vue';
import { createApp } from 'vue';
import { createPahoMqttPlugin } from 'vue-paho-mqtt';
createApp(App)
.use(
createPahoMqttPlugin({
PluginOptions: {
autoConnect: true,
showNotifications: true,
},
MqttOptions: {
host: 'localhost',
port: 9001,
clientId: `MyID-${Math.random() * 9999}`,
mainTopic: 'MAIN',
},
}),
)
.mount('#app');
```
### Quasar Framework ([quasar boot](https://quasar.dev/quasar-cli-vite/boot-files/))
```js
import { boot } from 'quasar/wrappers';
import { createPahoMqttPlugin } from 'vue-paho-mqtt';
export default boot(({ app }) => {
app.use(
createPahoMqttPlugin({
PluginOptions: {
autoConnect: true,
showNotifications: true,
},
MqttOptions: {
host: 'localhost',
port: 9001,
clientId: `MyID-${Math.random() * 9999}`,
mainTopic: 'MAIN',
},
}),
);
});
```
### Nuxt3 ([nuxt plugins](https://nuxt.com/docs/guide/directory-structure/plugins))
```ts
import { createPahoMqttPlugin } from 'vue-paho-mqtt';
export default defineNuxtPlugin({
name: 'vue-paho-mqtt',
enforce: 'pre',
async setup(nuxtApp) {
nuxtApp.vueApp.use(
createPahoMqttPlugin({
PluginOptions: {
autoConnect: true,
showNotifications: true,
},
MqttOptions: {
host: 'localhost',
port: 9001,
clientId: `MyID-${Math.random() * 9999}`,
mainTopic: 'MAIN',
},
}),
);
},
hooks: {
'app:created'() {
const nuxtApp = useNuxtApp();
},
},
});
```
---
## Options
### Plugin Options
You can configure the plugin by passing an object with the following options to `createPahoMqttPlugin`:
- `showNotifications` (`boolean`, default: `true`) - Whether to show error and success notifications.
- `autoConnect` (`boolean`, default: `true`) - Whether to automatically connect to the broker when the plugin is initialized.
### MQTT Options
You can configure the MQTT client by passing an object with the following options to `createPahoMqttPlugin`:
- `host` (`string`, default: `"localhost"`) - The hostname or IP address of the MQTT broker.
- `port` (`number`, default: `9001`) - The port number of the MQTT broker.
- `useSSL` (`boolean`, default: `false`) - Whether to use SSL when connecting to the broker.
- `clientId` (`string`, default: `"ClientID-${Math.random() * 9999}}"`) - The client identifier to use when connecting to the broker.
- `username` (`string`, default: `""`) - The username to use when connecting to the broker.
- `password` (`string`, default: `""`) - The password to use when connecting to the broker.
- `mainTopic` (`string`, default: `"MAIN"`) - If enaled, the topic that will be prepended to the topic specified during the $mqtt.publish and $mqtt.subscribe _(can be manually disabled in $mqtt.publish and $mqtt.subscribe)_.
- `enableMainTopic` (`boolean`, default: `true`) - Enables usage of the main topic.
- `watchdogTimeout` (`number`, default: `30000`) - The time in milliseconds to wait for a connection to the broker before timing out.
- `reconnectTimeout` (`number`, default: `5000`) - The time in milliseconds to wait before attempting to reconnect to the broker after a disconnection.
- `keepAliveInterval` (`number`, default: `60000`) - The server disconnects this client if there is no activity for this number of milliseconds.
- `cleanSession` (`boolean`, default: `true`) - Whether to delete the server persistent state on a new connection.
---
### MQTT Quality of Service (QoS) and Retention Options for Publish
The MQTT protocol provides Quality of Service (QoS) levels to control the reliability of message delivery between a publisher and a subscriber. Additionally, it provides the ability to retain messages, allowing subscribers to receive messages even if they connect after the message has been published.
The following are the MQTT QoS and retention options available for publishing messages:
| type | Option | QoS Level | Retain |
| ------ | ------ | :-------: | -----: |
| string | B | 0 | false |
| string | Br | 0 | true |
| string | Q | 1 | false |
| string | Qr | 1 | true |
| string | F | 2 | true |
| string | Fnr | 2 | false |
- **B**: QoS 0, non-retained message. The message is delivered at most once, and the broker does not store the message for future subscribers.
- **Br**: QoS 0, retained message. The message is delivered at most once, and the broker stores the message for future subscribers.
- **Q**: QoS 1, non-retained message. The message is delivered at least once, and the broker stores it until the publisher receives an acknowledgment from the subscriber.
- **Qr**: QoS 1, retained message. The message is delivered at least once, and the broker stores it until the publisher receives an acknowledgment from the subscriber. The broker also stores the message for future subscribers.
- **F**: QoS 2, retained message. The message is delivered exactly once, and the broker stores it for future subscribers.
- **Fnr**: QoS 2, non-retained message. The message is delivered exactly once, and the broker does not store it for future subscribers.
```ts
type MqttMode = 'B' | 'F' | 'Q' | 'Qr' | 'Br' | 'Fnr';
```
#### Example Usage with the $mqtt.publish
```ts
$mqtt.publish('test/topic', 'Hello, world!', 'Fnr');
```
---
## Notification Alerts
The Vue Paho MQTT plugin comes with built-in notifications using [SweetAlert2](https://sweetalert2.github.io/) library to display the notification alerts. _This library is already installed with the plugin_.
- `PluginOptions.showNotifications` (`boolean`, default: `true`) - Whether to show error and success alert notifications.
```ts
createPahoMqttPlugin({
PluginOptions: {
showNotifications: true,
...
}
...
```
| On | Icon | Title | Content | Timer |
| :----------------: | :-----: | :----------: | :---------------------------: | :---: |
| Connection Success | success | "Connected" | "MQTT Connected" | 1500 |
| Connection Failure | error | "Mqtt Error" | "MQTT failed to connect" | - |
| Connection Timeout | error | "Mqtt Error" | "Broker connection timed out" | - |
| Connection Lost | error | "Mqtt Error" | "MQTT connection lost" | - |
| Disconnect Error | error | "Error" | catch(error) => error.message | - |
| Connect Error | error | "Error" | catch(error) => error.message | - |
---
## Global MQTT client instance: $mqtt
## Connect
Connect to the MQTT broker. Shows a dialog notification in case of error if the plugin is configured to do so.
Custom callbacks can be passed to the connect function. Such as `onConnect`, `onFailure`, `onConnectionLost`, `onMessageArrived`.
- `onConnect()`: resolves the promise to `true` if the connection was successful.
- `onFailure()`: rejects the promise to `false` if the connection was unsuccessful.
- `onConnectionLost()`: returns an response object with the following properties:
- `errorCode`: the error code.
- `onMessageArrived()`:
returns a message object with the following properties:
- `payloadString`: the message payload as a string.
- `destinationName`: the name of the topic that the message was published to.
Note: Inside the 'subscribe' function a function is passed to the 'onMessageArrived' callback.
This function is used to parse the message payload and return the parsed message inside the subscribe
function where it is called.
You don't really need to handle arriving messages in the 'onMessageArrived' callback.
### Type Definition
```ts
const connect: ({
onConnect?: ((...args: unknown[]) => unknown) | undefined;
onFailure?: ((...args: unknown[]) => unknown) | undefined;
onConnectionLost?:
| ((
responseObject: {
errorCode: number;
},
...args: unknown[]
) => unknown)
| undefined;
onMessageArrived?:
| ((
message: {
payloadString: string;
destinationName: string;
},
...args: unknown[]
) => unknown)
| undefined;
}) => Promise;
```
### Usage
```ts
// Composition API
import { $mqtt } from 'vue-paho-mqtt';
$mqtt.connect();
// Options API
this.$mqtt.connect();
// or use it with async/await
const result = await $mqtt.connect();
// result will return "true" if the connection was successful
```
### Optional Custom Callbacks
| Callback | When | Return |
| :----------------: | :-----------------------------------------------: | :-------------------------------------------------------: |
| `onConnect` | successfully connected to the mqtt broker | - |
| `onFailure` | failed to connect to the mqtt broker | - |
| `onConnectionLost` | disconnected or connection lost connection | responseObject: {errorCode: number} |
| `onMessageArrived` | message arrived from one of the subscribed topics | message: {payloadString: string;destinationName: string;} |
#### Custom Callback Usage example
```ts
$mqtt.connect({
onConnect: () => {
console.log('Mqtt connected');
},
onFailure: () => {
console.log('Mqtt connection failed');
},
onConnectionLost: (error: any) => {
console.log('Error:', error.message);
},
onMessageArrived: (message: {
payloadString: string;
destinationName: string;
}) => {
console.log(
'Message Arrived:',
message.payloadString,
message.destinationName,
);
},
});
```
---
## Disconnect
Disconnect from the mqtt broker. Shows a dialog notification in case of error if the plugin is configured to do so.
### Type Definition
```ts
const disconnect: () => Promise;
```
### Usage
```ts
// Composition API
import { $mqtt } from 'vue-paho-mqtt';
$mqtt.disconnect();
// Options API
this.$mqtt.disconnect();
// or use it with async/await
const result = await $mqtt.disconnect();
// result will return "true" if the disconnection was successful
```
---
## Subscribe
It is used to subscribe to the topic specified, and to define the function to call when the specified topic recieves a message.
| param | type | explanation | default |
| :-----: | :------: | :----: | :---: |
| `topic` | `string` | MQTT topic to subscribe (ie: 'my/test/topic') | - |
| `onMessage` | `function` | Arrow function with a parameter to be fired when a message arrives to the specified topic | - |
| `useMainTopic` | `boolean` | main topic defined in the [MQTT Options](#mqtt-options) will be prepended to the topic specified | `true` |
### Type Definition
```ts
const subscribe: (
topic: string,
onMessage: (data: string, ...args: unknown[]) => unknown,
useMainTopic?: boolean,
) => void;
```
### Subscribe usage example
```ts
// if the enableMainTopic is true, subscribe to 'MAIN/my/topic'
this.$mqtt.subscribe('my/topic', (data: string) => {
console.log(data, 'recieved');
});
// even if the enableMainTopic is true, subscribe to 'my/topic'
this.$mqtt.subscribe(
'my/topic',
(data: string) => {
console.log(data, 'recieved');
},
false,
);
```
### Composition API
```ts
import { $mqtt } from 'vue-paho-mqtt';
$mqtt.subscribe('my/topic', (data: string) => {
console.log(data, 'recieved');
});
```
---
## Publish
Used to publish string data to the topic specified.
### Type Definition
```ts
const publish: (
topic: string,
payload: string,
mode: MqttMode,
useMainTopic?: boolean,
) => void;
```
| param | type | explanation | default |
| :------------: | :--------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-----: |
| `topic` | `string` | MQTT topic to publish (ie: 'my/test/topic') | - |
| `payload` | `string` | string payload to send | - |
| `mode` | `MqttMode` | See [MQTT Quality of Service (QoS) and Retention Options for Publish](#mqtt-quality-of-service-qos-and-retention-options-for-publish) for detailed explanation for mqtt mode options. [`"B"` \| `"F"` \| `"Q"` \| `"Qr"` \| `"Br"` \| `"Fnr"`] | - |
| `useMainTopic` | `boolean` | main topic defined in the [MQTT Options](#mqtt-options) will be prepended to the topic specified | `true` |
### Publish usage example
```ts
// if the enableMainTopic is true, publish to 'MAIN/my/topic'
// 'Fnr' => Qos: 2 , retained: false
this.$mqtt.publish('test/topic', 'Hello, world!', 'Fnr');
// even if the enableMainTopic is true, publish to 'my/topic'
// 'B' => Qos: 0 , retained: false
this.$mqtt.publish('test/topic', 'Hello, world!', 'B', false);
// if the enableMainTopic is true, publish to 'MAIN/my/topic'
// 'Qr' => Qos: 1 , retained: true
this.$mqtt.publish('test/topic', 'Hello, world!', 'Qr');
// payload: "Hello, world!"
```
### Composition API
```ts
import { $mqtt } from 'vue-paho-mqtt';
$mqtt.publish('test/topic', 'Hello, world!', 'Qr');
```
---
## Host
Get or set the host parameter from the [MQTT Options](#mqtt-options).
### Type Definition
```ts
const host: (e?: string) => string;
```
### Get Host
```ts
$mqtt.host(); // ie: "localhost"
```
### Set MQTT host
```ts
$mqtt.host('192.168.0.1');
```
### Example usage
```html
MQTT host: {{ $mqtt.host() }}
```
```ts
onMounted(() => {
console.log(this.$mqtt.host());
});
```
### Composition API
```ts
import { onMounted } from 'vue';
import { $mqtt } from 'vue-paho-mqtt';
onMounted(() => {
console.log($mqtt.host());
});
```
---
## Port
Get or set the port parameter from the [MQTT Options](#mqtt-options).
### Type Definition
```ts
const port: (e?: number) => number;
```
### Get Port
```ts
$mqtt.port(); // ie: 9001
```
### Set MQTT port
```ts
$mqtt.port(1234);
```
### Example usage
```html
MQTT port: {{ $mqtt.port() }}
```
```ts
onMounted(() => {
console.log(this.$mqtt.port());
});
```
### Composition API
```ts
import { onMounted } from 'vue';
import { $mqtt } from 'vue-paho-mqtt';
onMounted(() => {
console.log($mqtt.port());
});
```
---
## Path
Get or set the path parameter from the [MQTT Options](#mqtt-options).
### Type Definition
```ts
const path: (e?: string) => string;
```
### Get Path
```ts
$mqtt.path(); // ie: "/mqtt"
```
### Set MQTT path
```ts
$mqtt.path('/ws/mqtt');
```
### Example usage
```html
MQTT path: {{ $mqtt.path() }}
```
```ts
onMounted(() => {
console.log(this.$mqtt.path());
});
```
### Composition API
```ts
import { onMounted } from 'vue';
import { $mqtt } from 'vue-paho-mqtt';
onMounted(() => {
console.log($mqtt.path());
});
```
---
## Username
Get or set the username parameter from the [MQTT Options](#mqtt-options).
### Type Definition
```ts
const username: (e?: string) => string;
```
### Get Username
```ts
$mqtt.username(); // ie: ""
```
### Set MQTT username
```ts
$mqtt.username('testUsername');
```
### Example usage
```html
MQTT username: {{ $mqtt.username() }}
```
```ts
onMounted(() => {
console.log(this.$mqtt.username());
});
```
### Composition API
```ts
import { onMounted } from 'vue';
import { $mqtt } from 'vue-paho-mqtt';
onMounted(() => {
console.log($mqtt.username());
});
```
---
## Password
> [!CAUTION]
> Exposing the password to the client can cause security issues if not used properly.
Get or set the password parameter from the [MQTT Options](#mqtt-options).
### Type Definition
```ts
const password: (e?: string) => string;
```
### Get Password
```ts
$mqtt.password(); // ie: ""
```
### Set MQTT password
```ts
$mqtt.password('secret');
```
### Example usage
```html
MQTT password: {{ $mqtt.password() }}
```
```ts
onMounted(() => {
console.log(this.$mqtt.password());
});
```
### Composition API
```ts
import { onMounted } from 'vue';
import { $mqtt } from 'vue-paho-mqtt';
onMounted(() => {
console.log($mqtt.password());
});
```
---
## Client ID
Get or set the clientId parameter from the [MQTT Options](#mqtt-options).
### Type Definition
```ts
const clientId: (e?: string) => string;
```
### Get clientId
```ts
$mqtt.clientId(); // ie: "MyID-234"
```
### Set clientId
```ts
$mqtt.clientId('MyNewClientId');
```
### Example usage
```html
MQTT client id: {{ $mqtt.clientId() }}
```
```ts
onMounted(() => {
console.log(this.$mqtt.clientId());
});
```
### Composition API
```ts
import { onMounted } from 'vue';
import { $mqtt } from 'vue-paho-mqtt';
onMounted(() => {
console.log($mqtt.clientId());
});
```
---
## Main Topic
Get or set the mainTopic parameter from the [MQTT Options](#mqtt-options).
### Type Definition
```ts
const mainTopic: (e?: string) => string | undefined;
```
### Get mainTopic
```ts
$mqtt.mainTopic(); // ie: "MyID-234"
```
### Set MQTT mainTopic
```ts
$mqtt.mainTopic('MyNewClientId');
```
### Example usage
```html
MQTT mainTopic: {{ $mqtt.mainTopic() }}
```
```ts
onMounted(() => {
console.log(this.$mqtt.mainTopic());
});
```
### Composition API
```ts
import { onMounted } from 'vue';
import { $mqtt } from 'vue-paho-mqtt';
onMounted(() => {
console.log($mqtt.mainTopic());
});
```
---
## Unsubscribe
Used to unsubscribe from the topic specified
### Type Definition
```ts
const unsubscribe: (topic: string, useMainTopic?: boolean) => void;
```
| param | type | explanation | default |
| :------------: | :-------: | :----------------------------------------------------------------------------------------------: | :-----: |
| `topic` | `string` | MQTT topic to unsubscribe (ie: 'my/test/topic') | - |
| `useMainTopic` | `boolean` | main topic defined in the [MQTT Options](#mqtt-options) will be prepended to the topic specified | `true` |
### Unsubscribe usage example
```ts
// if the enableMainTopic is true, unsubscribe from 'MAIN/my/topic'
$mqtt.unsubscribe('test/topic');
// even if the enableMainTopic is true, unsubscribe from 'my/topic'
$mqtt.unsubscribe('test/topic', false);
```
---
## Unsubscribe All
Used to unsubscribe from **all** the topics subscribed previously.
### Type Definition
```ts
const unsubscribeAll: () => void;
```
### Usage
```ts
$mqtt.unsubscribeAll();
```
---
## Status
Used to get the status of the mqtt connection.
### Type Definition
```ts
type MqttStatus =
| 'connected'
| 'disconnected'
| 'connecting'
| 'error'
| 'lost'
| null;
const status: () => MqttStatus;
```
### Get MQTT Status
```ts
$mqtt.status(); // ie: "connected"
```
### Example usage
```html
MQTT Status: {{ $mqtt.status() }}
```
```ts
onMounted(() => {
console.log($mqtt.status());
});
```
---
## Usage Example
### Vue Options API
```typescript
mounted() {
// Connect to the mqtt broker
this.$mqtt.connect();
// Subscribe to a topic
this.$mqtt.subscribe("test/topic", (message: string) => {
console.log("Received message:", message);
});
// Publish a message
this.$mqtt.publish("test/topic", "Hello, world!", "F");
// Disconnect from the broker
this.$mqtt.disconnect();
}
```
### Vue Composition API
```typescript
import { onMounted } from "vue";
import { $mqtt } from 'vue-paho-mqtt';
onMounted(() => {
// Connect to the mqtt broker
$mqtt.connect();
// Subscribe to a topic
$mqtt.subscribe("test/topic", (message: string) => {
console.log("Received message:", message);
});
// Publish a message
$mqtt.publish("test/topic", "Hello, world!", "F");
// Disconnect from the broker
$mqtt.disconnect();
});
```
## Contributing
Contributions to the project is highly appreciated.
If you have any suggestions/questions/requests please consider
[opening an issue](https://github.com/kaandesu/vue-paho-mqtt/issues/new). If you want to contribute to the project, fixing an open issue is greatly recommended and appreciated. To see the all contribution rules please check the [contribution rules](CONTRIBUTING.md).
## License
This project is licensed under `MIT License` if you want to see more, please check [LICENSE](LICENSE) for more information.
## Credits
This project is created and actively maintained by [kaandesu](https://github.com/kaandesu) and [EgeOnder](https://github.com/EgeOnder)
### Contact
| Maintainer | E-Mail | Twitter |
| --------------------------------------- | ------------------------------------------ | --------------------------------------------- |
| [kaandesu](https://github.com/kaandesu) | | - |
| [EgeOnder](https://github.com/EgeOnder) | <[email protected]> | [@EgeOnder23](https://twitter.com/EgeOnder23) |
## Changelog
Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
## Security
The security policy of the project can be found in [SECURITY.md](SECURITY.md). If you find any security issues, please refer to the policy. Thank you.