# 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](/content/docs/sdk#features/index.html)

- **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](/content/docs/sdk/custom-persistence/index.html).

## [Installation](/content/docs/sdk#installation/index.html)

npmpnpmyarnbun

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

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

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

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

## [Quick Start](/content/docs/sdk#quick-start/index.html)

```javascript
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](/content/docs/sdk#architecture/index.html)

```
┌─────────────────────────────────────────────────────────┐
│                    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](/content/docs/sdk#next-steps/index.html)

[**Getting Started** Installation, setup, and configuration.](/content/docs/sdk/getting-started/index.html) [**Managing Bridges** Add, remove, and connect to bridges.](/content/docs/sdk/bridges/index.html) [**Hooks Reference** All available hooks and their usage.](/content/docs/sdk/hooks/index.html) [**Utilities** Helper functions for formatting data.](/content/docs/sdk/utils/index.html)

[Getting Started Install and configure the SDK in your React app.](/content/docs/sdk/getting-started/index.html)