@hiyve/react-semantic-relay

React provider + hooks for the Hiyve Semantic Relay — high-frequency, fire-and-forget, room-scoped messaging. Connects over WebTransport (QUIC datagrams, preferred) with automatic WebSocket fallback, so it works in every current browser and on networks that block UDP.

Installation

npm install @hiyve/react-semantic-relay @hiyve/semantic-relay-client
Copy

Quick start

import { SemanticRelayProvider, useRelayTopic } from '@hiyve/react-semantic-relay';

function App() {
  return (
    <SemanticRelayProvider
      url="https://semantic.hiyve.tv:4443/relay"
      roomId="lesson-abc"
      userId="alice@example.com"
      token={jwtFromBackend}
      serverCertificateHashes={certHashes}
    >
      <Instruments />
    </SemanticRelayProvider>
  );
}

function Instruments() {
  const { publish, subscribe, isConnected } = useRelayTopic<{ midi: number; on: boolean }>(
    'instrument-notes',
  );

  useEffect(() => subscribe(({ payload, userId }) => {
    console.log(`${userId} played`, payload);
  }), [subscribe]);

  return (
    <button disabled={!isConnected} onClick={() => publish({ midi: 60, on: true })}>
      Play C
    </button>
  );
}
Copy

Requirements

• A running Hiyve Semantic Relay server (serves WebTransport over UDP and the WebSocket fallback over TCP on the same endpoint).
• A short-lived JWT minted by your backend, scoped to a roomId + userId.
• For self-signed development certs, the SHA-256 certificate hashes (serverCertificateHashes) — browsers refuse to connect over WebTransport without this when not using a public CA. The WebSocket fallback has no hash-pinning mechanism and requires the relay's TCP listener to serve a CA-trusted certificate.
• Any current browser — transport selection is automatic (WebTransport where available and connectable, WebSocket everywhere else).
• Peer dependencies: react ^18, @hiyve/semantic-relay-client.

API

<SemanticRelayProvider>

Provides a relay connection to descendants. Reconnects automatically when connection identity (url / roomId / userId / token) changes.

useSemanticRelay()

Returns { client, state, session, isConnected, error, transportKind }. Use this for lower-level access — most consumers only need useRelayTopic. transportKind reports which transport the live connection uses ('webtransport' or 'websocket'), or null before connect.

useRelayTopic<T>(topic)

Returns { publish, subscribe, isConnected }. The subscribe callback returns an unsubscribe function suitable for a useEffect cleanup.

useRelaySubProtocol<T>(options)

Reliable per-message pub/sub on a topic — a drop-in replacement for the WebRTC data-channel sendDataMessage / 'data-message' listener pattern. On top of useRelayTopic it adds self-message filtering, bounded message dedup, transparent chunking for payloads above the datagram cap, and per-message acknowledgement with automatic retry.

const { publish, isConnected } = useRelaySubProtocol<{ x: number; y: number }>({
  topic: 'myapp.cursor.move',
  localUserId,
  onMessage: (payload, meta) => applyRemotePoint(payload, meta.senderId),
  onError: (err) => console.warn('sub-protocol:', err.message),
});

publish({ x: 0.5, y: 0.5 });                    // acked + retried by default
publish({ x, y }, { requireAck: false });       // fire-and-forget (high-rate signals)
publish(edit, { ackFrom: authorUserId });       // targeted: only the author's ack counts
Copy

Options: topic, localUserId, onMessage(payload, meta), onError(err), dedupWindow (default 200), ignoreOwnMessages (default true), defaultRequireAck (default true).

Per-publish options (PublishOptions):

When a message exhausts its retry budget without the required ack, onError fires with a descriptive Error.

Key Types

Capability probes

License

MIT