react-native-freedome

React Native bindings for Freedome domes over @freedome/client: one provider, a handful of hooks, secure token storage, mDNS discovery and freedome://pair links.

Licence: NativeMindNONC — see LICENSE. Non-commercial use is free under the licence terms; commercial use requires a licence from NativeMind sales (https://freedome.nativemind.us/commercial). Support: support@freedome.nativemind.net. Upgrading from 0.1.x: see MIGRATION.md.

Install

npm install react-native-freedome @freedome/client
# optional native modules (dev build / prebuild, not Expo Go):
npm install react-native-encrypted-storage   # token storage in Keychain / EncryptedSharedPreferences
npm install react-native-zeroconf            # mDNS discovery of _freedome._tcp

Peer dependencies: react ≥ 18.2, react-native ≥ 0.74; react-native-encrypted-storage and react-native-zeroconf are optional and only loaded from their subpaths. Hermes needs crypto.getRandomValues (e.g. expo-crypto or react-native-get-random-values). iOS discovery needs NSBonjourServices: ["_freedome._tcp"] and NSLocalNetworkUsageDescription.

Use

import { FreeDomeProvider, useConnection, usePlayback, PlayTargets } from 'react-native-freedome';
import { encryptedTokenStore } from 'react-native-freedome/encrypted-storage';
import { zeroconfBrowser } from 'react-native-freedome/zeroconf';

export default function App() {
  return (
    <FreeDomeProvider
      appId="net.example.app"
      appName="Example"
      appVersion="1.0.0"
      tokenStore={encryptedTokenStore()}
      discovery={zeroconfBrowser()}
    >
      <Remote />
    </FreeDomeProvider>
  );
}

function Remote() {
  const { state, errorCode, pairingCode, connect, pair } = useConnection();
  const player = usePlayback();
  // connect('192.168.1.20') or pair('freedome://pair?host=…&code=…'); show pairingCode until approved on the dome
  // player.play(PlayTargets.show(showId)); player.pause(); player.seek(30_000); player.setVolume(0.5)
}

API	What it does
<FreeDomeProvider>	Owns one FreedomeClient (or follows an external client); endpoint auto-connects; app lifecycle → background grace / resume; props tokenStore, discovery, transports, options, logger
useFreeDome()	{ client, state, connected, error, pairingCode, connect, pair, disconnect, logout, quickPlay (deprecated) }
useConnection()	state machine state, isOnline, isBusy, errorCode, pairingCode, connect / pair / disconnect
usePlayback({playerId, venueId})	player state (status, stale) + play / pause / resume / stop / next / previous / seek(ms) / setVolume(0..1)
useAudio({venueId, zones, generator})	audio state, zones, generator state + setMasterGain / setMasterMute / setMaster / setZoneGain / setZoneMute / startGenerator / stopGenerator
useDomeDiscovery({browser, timeoutMs})	nearby domes (_freedome._tcp, deduplicated by TXT id), scanning, error, start / stop
usePairingLinks()	pairs when the app opens a freedome://pair?… link (register the freedome URL scheme)
EncryptedTokenStore(storage)	TokenStore over any {getItem, setItem, removeItem} secure storage
/encrypted-storage, /zeroconf	encryptedTokenStore(), zeroconfBrowser() — the native-module wiring

Errors carry stable codes (FreedomeError.code: unauthenticated, forbidden, offline, timeout, not-connected, validation, discovery-unavailable, …). Live control (playback, audio master / zones / generator) fails fast while offline and is never queued.

Tests

pnpm -F react-native-freedome test — jest with the react-native preset and @testing-library/react-native (renderHook, react-test-renderer 19) in Node 22, no device; @freedome/client is mapped to its sources and its in-memory fake (@freedome/client/testing). test:integration runs the provider against a freedome/fake-dome container (FD_FAKE_URL, FD_FAKE_KEY; see tool/docker-check.sh integration).