Introduction

The @deskctl/sdk package provides React hooks and utilities for connecting to Deskctl 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

npm install @deskctl/sdk @tanstack/react-query

pnpm add @deskctl/sdk @tanstack/react-query

yarn add @deskctl/sdk @tanstack/react-query

bun add @deskctl/sdk @tanstack/react-query

Quick Start

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { BridgesProvider, useBridges, useSystemStats } from "@deskctl/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             │
└─────────────────────────────────────────────────────────┘