@artcom/mqtt-topping-react

A React wrapper for @artcom/mqtt-topping providing hooks and context for easy MQTT and HTTP integration.

Installation

npm install @artcom/mqtt-topping-react

Note: This package includes @artcom/mqtt-topping and @tanstack/react-query as dependencies, so you don't need to install them separately.

Usage

MqttProvider

Wrap your application with MqttProvider. You can provide a suspenseFallback to handle the initial connection state automatically.

import { MqttProvider } from "@artcom/mqtt-topping-react"

function App() {
  return (
    <MqttProvider
      uri="ws://broker.hivemq.com:8000/mqtt"
      httpBrokerUri="http://broker.hivemq.com:8000/query" // Optional: for useMqttQuery
      suspenseFallback={<div>Connecting to MQTT...</div>} // Optional: shows this while connecting
    >
      <YourApp />
    </MqttProvider>
  )
}

Hooks

useMqttSubscribe

Subscribe to a topic.

import { useMqttSubscribe } from "@artcom/mqtt-topping-react"

function MyComponent() {
  useMqttSubscribe("my/topic", (payload, topic) => {
    console.log("Received:", payload)
  })

  return <div>Listening...</div>
}

useHttpClient

Access the HTTP client directly.

import { useHttpClient } from "@artcom/mqtt-topping-react"

function MyComponent() {
  const httpClient = useHttpClient()

  const fetchData = async () => {
    const data = await httpClient?.queryJson("my/topic")
    console.log(data)
  }

  return <button onClick={fetchData}>Fetch</button>
}

useMqttQuery

Fetch data using TanStack Query integration. This provides caching, loading states, and error handling out of the box. Requires httpBrokerUri to be set in MqttProvider.

import { useMqttQuery } from "@artcom/mqtt-topping-react"

function MyComponent() {
  const { data, isLoading, error } = useMqttQuery("my/topic")

  if (isLoading) return <div>Loading...</div>
  if (error) return <div>Error: {error.message}</div>

  return <div>Data: {JSON.stringify(data)}</div>
}

useMqttQueryBatch

Fetch multiple topics in a single batch request.

import { useMqttQueryBatch } from "@artcom/mqtt-topping-react"

function MyComponent() {
  const { data, isLoading, error } = useMqttQueryBatch(["topic/1", "topic/2"])

  if (isLoading) return <div>Loading...</div>
  if (error) return <div>Error: {error.message}</div>

  return (
    <div>
      {data?.map((result, index) => (
        <div key={index}>{JSON.stringify(result)}</div>
      ))}
    </div>
  )
}

useMqttUnpublishRecursively

Unpublish a topic and all its subtopics recursively.

import { useMqttUnpublishRecursively } from "@artcom/mqtt-topping-react"

function MyComponent() {
  const unpublishRecursively = useMqttUnpublishRecursively()

  const handleCleanup = async () => {
    await unpublishRecursively("my/topic")
  }

  return <button onClick={handleCleanup}>Cleanup</button>
}

API Reference

MqttProvider Props

| Prop | Type | Description | | ------------------ | ------------------- | --------------------------------------------------------------------------- | | uri | string | The MQTT broker URI (e.g., tcp://localhost:1883 or ws://localhost:9001) | | options | MqttClientOptions | Optional configuration for the MQTT client | | httpBrokerUri | string | Optional URI for the HTTP interface of the broker | | httpOptions | HttpClientOptions | Optional configuration for the HTTP client | | suspenseFallback | ReactNode | Optional fallback UI to show while connecting | | children | ReactNode | Child components |