Introduction

React SDK for building Cntrl Bridge dashboards.

The @cntrl-pw/sdk package provides React hooks and utilities for connecting to Cntrl Bridge devices. It handles WebSocket connections, state management, and provides a simple API for building dashboards.

Features

• Multiple Bridges - Connect to multiple Bridge devices simultaneously
• Real-time Updates - WebSocket subscriptions with automatic reconnection
• React Query Integration - Caching, deduplication, and optimistic updates
• Persistent Storage - Bridge configs saved to localStorage via Zustand
• TypeScript - Full type safety for all API responses

Storage Support

By default, bridges are persisted to localStorage via Zustand. You can plug in a custom storage backend (IndexedDB, SQLite, REST API) — see Custom Storage.

Installation

npmpnpmyarnbun

npm install @cntrl-pw/sdk @tanstack/react-query

pnpm add @cntrl-pw/sdk @tanstack/react-query

yarn add @cntrl-pw/sdk @tanstack/react-query

bun add @cntrl-pw/sdk @tanstack/react-query

Quick Start

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { BridgesProvider, useBridges, useSystemStats } from "@cntrl-pw/sdk";

const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <BridgesProvider>
        <Dashboard />
      </BridgesProvider>
    </QueryClientProvider>
  );
}

function Dashboard() {
  const { bridges, addBridge } = useBridges();

const handleAddBridge = () => {
    addBridge({
      name: "My PC",
      config: { host: "192.168.1.100", port: 9990 },
    });
  };

return (
    <div>
      <button onClick={handleAddBridge}>Add Bridge</button>
      {Array.from(bridges.values()).map((bridge) => (
        <BridgeCard key={bridge.id} bridgeId={bridge.id} />
      ))}
    </div>
  );
}

function BridgeCard({ bridgeId }: { bridgeId: string }) {
  const { data } = useSystemStats(bridgeId);

if (!data) return <div>Loading...</div>;

return (
    <div>
      <p>CPU: {data.cpu.current_load.toFixed(1)}%</p>
      <p>RAM: {data.memory.percent.toFixed(1)}%</p>
    </div>
  );
}

Architecture

┌─────────────────────────────────────────────────────────┐
│                    BridgesProvider                       │
│  - Manages WebSocket connections (one per bridge)       │
│  - Syncs with Zustand store for persistence             │
│  - Routes WS messages to React Query cache              │
├─────────────────────────────────────────────────────────┤
│                      React Hooks                         │
│  useSystemStats(bridgeId)  → WS subscription            │
│  useMedia(bridgeId)        → WS + mutations             │
│  useProcesses(bridgeId)    → WS + mutations             │
│  useSystemInfo(bridgeId)   → REST (cached)              │
│  usePower(bridgeId)        → REST mutations             │
└─────────────────────────────────────────────────────────┘

Next Steps

Getting Started Installation, setup, and configuration. Managing Bridges Add, remove, and connect to bridges. Hooks Reference All available hooks and their usage. Utilities Helper functions for formatting data.

Getting Started Install and configure the SDK in your React app.