react-native-freedome
v1.0.0
Published
React Native bindings over @freedome/client: FreeDomeProvider, useFreeDome, useConnection, usePlayback, useAudio, useDomeDiscovery (react-native-zeroconf), encrypted token storage, freedome://pair links.
Maintainers
Readme
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: [email protected]. 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._tcpPeer 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).
