https://github.com/victorhas/mqtt-react-hooks
ReactJS library for Pub/Sub communication with an MQTT broker using Hooks
https://github.com/victorhas/mqtt-react-hooks
hooks mqtt mqtt-broker mqtt-react-hooks reactjs topic
Last synced: about 1 month ago
JSON representation
ReactJS library for Pub/Sub communication with an MQTT broker using Hooks
- Host: GitHub
- URL: https://github.com/victorhas/mqtt-react-hooks
- Owner: VictorHAS
- License: mit
- Archived: true
- Created: 2020-02-07T02:34:39.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2023-02-04T11:50:26.000Z (over 3 years ago)
- Last Synced: 2024-12-14T13:36:43.160Z (over 1 year ago)
- Topics: hooks, mqtt, mqtt-broker, mqtt-react-hooks, reactjs, topic
- Language: TypeScript
- Size: 1.64 MB
- Stars: 92
- Watchers: 1
- Forks: 28
- Open Issues: 32
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.MD
- Security: SECURITY.md
Awesome Lists containing this project
README
[](https://www.npmjs.com/package/mqtt-react-hooks)
[](https://github.com/VictorHAS/mqtt-react-hooks/actions/workflows/publish.yml)
## Overview
> **A note from the author**: Sorry for the lack of updates since 2021! I originally built this library for my graduation project when I was very new to programming. Today, with a deeper understanding and far better tools, I've finally come back to fix everything and transform this into the library it was always meant to be. Thank you for your patience!
This library is focused in help you to connect, publish and subscribe to a Message Queuing Telemetry Transport (MQTT) in ReactJS with the power of React Hooks.
## 🚀 Version 3.0.0 - Major Architecture Rewrite!
Version `3.0.0` introduces a globally scalable **SubscriptionManager multiplexer**.
* **Zero Event Duplication**: Calling `useSubscription` inside multiple nested components no longer spawns duplicate `client.on('message')` listeners. Everything routes perfectly through a single Singleton-Context listener.
* **Intelligent Reference Counting**: The broker only `.subscribe`s over the network on the first mount. When the very last matching hook unmounts, it safely triggers `.unsubscribe()`.
* **Pre-Hydrated Cache**: If a sensor event occurs and a React hook mounts a few seconds later, it instantly loads the *cached payload*.
* **Upgraded Core**: Powered natively by the highly robust latest `mqtt` v5 implementation.
## Installation
Just add `mqtt-react-hooks` and `mqtt` to your project:
```bash
npm add mqtt-react-hooks mqtt
```
### Exported Hooks
- `useMqttState` -> returns `{ connectionStatus, client, message }`
- `useSubscription(topic: string | string[], options?: {} )` -> returns `{ client, topic, message, connectionStatus }`
---
## Usage
Similarly to `react-redux`, you must first wrap your application (or subtree) with a `` which will initialize the internal Mqtt Client instance and Subscription Multiplexer.
### Root component
The only required prop is `brokerUrl`. Additional options follow the standard [mqtt.Client#connect](https://github.com/mqttjs/MQTT.js#connect) schema.
```tsx
import React from 'react';
import { Connector } from 'mqtt-react-hooks';
import Status from './Status';
export default function App() {
return (
);
}
```
### Connection Status
Use `useMqttState` to universally extract the internal connection variables safely without subscribing to topics.
```tsx
import React from 'react';
import { useMqttState } from 'mqtt-react-hooks';
export default function Status() {
/*
* Status strings:
* - Connecting
* - Connected
* - Reconnecting
* - Offline
* - Error
*/
const { connectionStatus } = useMqttState();
return
{`Status: ${connectionStatus}`}
;
}
```
### Subscribing to Overlapping Topics
Multiple components can subscribe directly to arrays or exact wildcard filters independently without clashing.
```tsx
import React from 'react';
import { useSubscription } from 'mqtt-react-hooks';
export default function RoomGauges() {
/* Message structure:
* topic: string
* message: string (or Buffer depending on parser)
*/
const { message } = useSubscription([
'room/livingroom/temperature',
'room/kitchen/temperature',
]);
return (
Latest Update: {message?.topic}
{message?.message}°C
);
}
```
### Publishing Messages
You don't need a topic subscription if you just want to publish! You can use `useMqttState` (or pass an empty array to `useSubscription([])`) to just grab the raw client object:
```tsx
import React from 'react';
import { useSubscription } from 'mqtt-react-hooks';
export default function SwitchButton() {
const { client } = useSubscription([]);
function handleClick() {
client?.publish('room/livingroom/lights', 'OFF');
}
return (
Disable Lights
);
}
```
## Tips
### Bundler Troubleshooting (Vite / Webpack)
If your specific bundler configuration struggles to resolve Node-specific modules (like `Buffer` or `process`) natively, or if you run into strict ESM resolution errors, check out the [MQTT.js Bundle documentation](https://github.com/mqttjs/MQTT.js#bundle). MQTT.js provides pre-built browser-optimized distributions (e.g., `mqtt/dist/mqtt.min`) which you can alias or import directly if needed.
## Contributing
Thanks for being interested on making this package better. We encourage everyone to help improving this project with some new features, bug fixes and performance issues. Please take a little bit of your time to read our guides, so this process can be faster and easier.
## License
MIT ©