@wklm/react

@wklm/react - Production-Grade Web Bluetooth SDK for React

A production-ready React SDK for Web Bluetooth, enabling seamless BLE device integration in your React applications. Works with the WebBLE Safari Extension to provide full Web Bluetooth API support across all browsers.

Features

• 🎯 One-line integration - Get started in under 5 minutes
• 🔄 Full Web Bluetooth API - 100% specification compliance
• ⚛️ React-first design - Hooks and components that feel native
• 📦 Tiny bundle - <50KB gzipped with tree-shaking
• 🔒 Type-safe - Complete TypeScript definitions
• 🚀 Production-ready - 91% test coverage, battle-tested
• 🔋 Battery-included - UI components, auto-reconnect, caching

Installation

npm install @wklm/react
# or
yarn add @wklm/react
# or
pnpm add @wklm/react

Quick Start

Basic Setup

import { WebBLE } from '@wklm/react';

function App() {
  return (
    <WebBLE.Provider>
      <YourApp />
    </WebBLE.Provider>
  );
}

Connect to a Device

import { WebBLE } from '@wklm/react';

function MyComponent() {
  const { requestDevice, isAvailable } = WebBLE.useBluetooth();

  const handleConnect = async () => {
    const device = await requestDevice({
      filters: [{ services: ['heart_rate'] }]
    });
    
    if (device) {
      console.log('Connected to', device.name);
    }
  };

  if (!isAvailable) {
    return <div>Bluetooth not available</div>;
  }

  return (
    <button onClick={handleConnect}>
      Connect to Heart Rate Monitor
    </button>
  );
}

Core Hooks

useBluetooth()

Main hook for Bluetooth operations.

const {
  isAvailable,           // Is Web Bluetooth available?
  isExtensionInstalled,   // Is WebBLE extension installed?
  requestDevice,          // Request device from user
  getDevices,            // Get paired devices
  requestLEScan          // Start BLE scanning
} = WebBLE.useBluetooth();

useDevice(deviceId)

Manage a specific Bluetooth device.

const {
  device,                // Device object
  isConnected,           // Connection status
  connect,               // Connect to device
  disconnect,            // Disconnect from device
  services,              // Available GATT services
  connectionState,       // 'connecting' | 'connected' | 'disconnecting' | 'disconnected'
  rssi                   // Signal strength
} = WebBLE.useDevice(deviceId);

useCharacteristic(characteristicId)

Read/write BLE characteristics.

const {
  value,                 // Current value (DataView)
  properties,            // Characteristic properties
  readValue,             // Read from characteristic
  writeValue,            // Write to characteristic
  startNotifications,    // Subscribe to changes
  stopNotifications      // Unsubscribe from changes
} = WebBLE.useCharacteristic(characteristicId);

useNotifications(characteristicId)

Real-time notifications from BLE devices.

const {
  value,                 // Latest value
  isSubscribed,          // Subscription status
  subscribe,             // Start notifications
  unsubscribe,           // Stop notifications
  history                // Value history
} = WebBLE.useNotifications(characteristicId);

useScan(options)

Scan for nearby BLE devices.

const {
  isScanning,            // Scan status
  devices,               // Found devices
  startScan,             // Begin scanning
  stopScan,              // Stop scanning
  error                  // Scan errors
} = WebBLE.useScan({
  filters: [{ namePrefix: 'Device' }],
  keepRepeatedDevices: true
});

useConnection(deviceId)

Advanced connection management.

const {
  connectionState,       // Detailed state
  connectionQuality,     // Signal quality
  reconnect,             // Manual reconnect
  connectionPriority,    // Get/set priority
  setConnectionPriority  // Update priority
} = WebBLE.useConnection(deviceId);

UI Components

<DeviceScanner />

Full-featured device selection UI.

<WebBLE.DeviceScanner
  filters={[{ services: ['heart_rate'] }]}
  onDeviceSelected={(device) => console.log('Selected:', device)}
  showSignalStrength
  autoConnect
/>

<ServiceExplorer />

GATT service/characteristic explorer.

<WebBLE.ServiceExplorer
  deviceId={deviceId}
  expandedByDefault
  showRawValues
  onCharacteristicRead={(char, value) => console.log(char, value)}
/>

<ConnectionStatus />

Connection state indicator.

<WebBLE.ConnectionStatus
  deviceId={deviceId}
  showDetails
  showSignalStrength
  className="connection-indicator"
/>

<InstallationWizard />

Extension installation helper.

<WebBLE.InstallationWizard
  onComplete={() => console.log('Extension installed!')}
  className="install-wizard"
/>

Advanced Usage

Auto-Reconnection

const provider = (
  <WebBLE.Provider config={{
    autoReconnect: true,
    reconnectAttempts: 5,
    reconnectDelay: 1000
  }}>
    <App />
  </WebBLE.Provider>
);

Custom GATT Caching

const { device } = WebBLE.useDevice(deviceId, {
  cacheTimeout: 60000,  // Cache for 1 minute
  cachePolicy: 'write-through'
});

Error Handling

function MyComponent() {
  const { requestDevice } = WebBLE.useBluetooth();
  
  const connect = async () => {
    try {
      const device = await requestDevice();
      // Handle device
    } catch (error) {
      if (error.name === 'NotFoundError') {
        // User cancelled
      } else if (error.name === 'NotAllowedError') {
        // Permission denied
      }
    }
  };
}

TypeScript Support

import { WebBLE, BluetoothDevice, BluetoothService } from '@wklm/react';

interface HeartRateData {
  heartRate: number;
  contactDetected: boolean;
}

function useHeartRate(device: BluetoothDevice): HeartRateData | null {
  const { value } = WebBLE.useNotifications('heart_rate_measurement');
  
  if (!value) return null;
  
  return {
    heartRate: value.getUint8(1),
    contactDetected: Boolean(value.getUint8(0) & 0x01)
  };
}

Examples

Heart Rate Monitor

function HeartRateMonitor() {
  const { requestDevice } = WebBLE.useBluetooth();
  const [deviceId, setDeviceId] = useState<string>();
  const { device, isConnected } = WebBLE.useDevice(deviceId);
  const { value } = WebBLE.useNotifications('heart_rate_measurement');
  
  const connect = async () => {
    const device = await requestDevice({
      filters: [{ services: ['heart_rate'] }]
    });
    if (device) setDeviceId(device.id);
  };
  
  const heartRate = value ? value.getUint8(1) : 0;
  
  return (
    <div>
      {!isConnected ? (
        <button onClick={connect}>Connect</button>
      ) : (
        <div>Heart Rate: {heartRate} BPM</div>
      )}
    </div>
  );
}

Smart Light Control

function SmartLight({ deviceId }: { deviceId: string }) {
  const { writeValue } = WebBLE.useCharacteristic('light_control');
  
  const setColor = (r: number, g: number, b: number) => {
    const data = new Uint8Array([r, g, b]);
    writeValue(data);
  };
  
  return (
    <div>
      <button onClick={() => setColor(255, 0, 0)}>Red</button>
      <button onClick={() => setColor(0, 255, 0)}>Green</button>
      <button onClick={() => setColor(0, 0, 255)}>Blue</button>
    </div>
  );
}

Browser Support

Browser	Support	Notes
Safari 16+	✅ Full	Requires WebBLE Extension
Chrome 56+	✅ Full	Native support
Edge 79+	✅ Full	Native support
Firefox	⚠️ Partial	Behind flag
iOS Safari	✅ Full	Requires WebBLE Extension

API Reference

Provider Props

interface WebBLEProviderProps {
  config?: {
    autoReconnect?: boolean;
    reconnectAttempts?: number;
    reconnectDelay?: number;
    cacheTimeout?: number;
    debugMode?: boolean;
  };
  children: ReactNode;
}

Device Options

interface RequestDeviceOptions {
  filters?: Array<{
    services?: string[];
    name?: string;
    namePrefix?: string;
    manufacturerData?: Array<{
      companyIdentifier: number;
      dataPrefix?: ArrayBuffer;
    }>;
  }>;
  optionalServices?: string[];
  acceptAllDevices?: boolean;
}

Scan Options

interface BluetoothLEScanOptions {
  filters?: BluetoothLEScanFilter[];
  keepRepeatedDevices?: boolean;
  acceptAllAdvertisements?: boolean;
}

Contributing

We welcome contributions! Please see our Contributing Guide for details.

# Clone the repo
git clone https://github.com/wklm/WebBLE-Safari-Extension.git

# Install dependencies
cd packages/react-sdk
npm install

# Run tests
npm test

# Build
npm run build

Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run in watch mode
npm run test:watch

License

MIT © wklm

Support

• 📖 Documentation
• 🐛 Report Issues
• 💬 Discussions
• 📧 Email Support

Acknowledgments

Built with the WebBLE Safari Extension to bring Web Bluetooth to all browsers.