Connect from JavaScript

Connect a browser or Node.js app to CloudSignal using @cloudsignal/mqtt-client. The SDK handles WebSocket transport, token authentication, reconnection, and platform presets. Use this when you want to publish and subscribe to MQTT topics from JavaScript or TypeScript.

Install

npm install @cloudsignal/mqtt-client

The SDK ships with TypeScript types and ESM + CommonJS bundles.

Connect

The SDK supports two authentication paths. Pick the one that matches where your code runs.

import CloudSignal from '@cloudsignal/mqtt-client';
import { supabase } from './lib/supabase';

const client = new CloudSignal({ preset: 'desktop' });

const { data: { session } } = await supabase.auth.getSession();

await client.connectWithToken({
  organizationId: process.env.NEXT_PUBLIC_CLOUDSIGNAL_ORG_ID,
  externalToken: session.access_token,
});
// → connection established, credentials valid for ~60 minutes

import CloudSignal from '@cloudsignal/mqtt-client';

const client = new CloudSignal({ preset: 'server' });

await client.connectWithToken({
  organizationId: process.env.CLOUDSIGNAL_ORG_ID,
  secretKey: process.env.CLOUDSIGNAL_SECRET_KEY,
  userEmail: 'service@example.com',
});
// → connection established

Subscribe and publish

Once connected, subscribe to a topic and listen for messages. Publish with transmit. Both calls are awaitable.

client.onMessage((topic, message) => {
  console.log('received', topic, message);
});

await client.subscribe('agents/agent-01/state');

client.transmit('agents/agent-01/state', {
  status: 'idle',
  load: 0.12,
});
// → published to broker

The first argument to transmit is the topic, the second is the payload. The SDK serializes objects to JSON automatically.

Disconnect

Tear down the connection cleanly when you're done. In React, call this from the cleanup phase of your effect.

client.destroy();

React example

A minimal hook that connects on mount, subscribes to a topic, and disconnects on unmount:

import { useEffect, useRef, useState } from 'react';
import CloudSignal from '@cloudsignal/mqtt-client';

export function useAgentState(agentId: string, accessToken: string) {
  const [state, setState] = useState(null);
  const clientRef = useRef<CloudSignal | null>(null);

  useEffect(() => {
    const client = new CloudSignal({ preset: 'desktop' });
    clientRef.current = client;

    client.onMessage((_topic, message) => setState(message));

    client.connectWithToken({
      organizationId: process.env.NEXT_PUBLIC_CLOUDSIGNAL_ORG_ID,
      externalToken: accessToken,
    }).then(() => client.subscribe(`agents/${agentId}/state`));

    return () => client.destroy();
  }, [agentId, accessToken]);

  return state;
}

Stability markers

@cloudsignal/mqtt-client is on its 2.x line and considered stable for production workloads. Breaking API changes ship in major versions; minor versions are additive.

Next steps

• SDK catalog - Browse the full set of @cloudsignal/* packages
• Connection parameters - Hosts, ports, and TLS configuration
• Token exchange API - The endpoint the SDK calls for browser auth
• @cloudsignal/mqtt-client on npm - Full method reference and changelog