Debug React Native TV apps with Buoy

Start with a compatible react-native-tvos development build. Focus Inspector requires New Architecture event support. Follow native setup requirements for your selected packages; a Metro restart alone may not be sufficient.

npm install @buoy-gg/core @buoy-gg/external-sync @buoy-gg/tv-remote @buoy-gg/focus-inspector
npx --package=@buoy-gg/core buoy login

For Expo, use the account key the CLI saved to your env file. React Native CLI apps must supply the key through their own environment configuration. Mount Buoy inside any providers required by your selected tools:

import { FloatingDevTools } from "@buoy-gg/core";

// Add alongside your app content, inside the required providers.
<FloatingDevTools
  headless
  licenseKey={process.env.EXPO_PUBLIC_BUOY_KEY}
  externalSync={{ deviceName: "Living Room TV" }}
/>

Open Buoy Desktop, sign in and select the TV connection. For an Android TV emulator, forward the broker port to the host:

adb -s <serial> reverse tcp:42831 tcp:42831

Physical devices need a reachable broker address. Follow the TV installation guide for connection and host-tool setup.

Focusable overlays can affect D-pad navigation. Headless mode avoids adding Buoy's floating menu to the screen while keeping supported capture and sync active. It does not configure every store or router automatically.

Compare a known focus path with capture enabled and disabled if you suspect interference. A successful check in one app does not prove zero overhead or identical focus behavior in every layout.

Record a short remote sequence and compare the events with what the TV did. Focus findings are heuristics: an unvisited element is not necessarily unreachable. Check your layout and focus guides before treating a flag as a defect.

See the TV Remote and Focus Inspector guides for recording, scanning and action limits.

Desktop sends host input; the TV package observes events delivered to the app. Not every OS-level event reaches JavaScript. The Apple TV simulator path needs idb installed separately from Xcode. Use the installation guide for the host commands.

Install the inspectors your app needs and configure their adapters. Data availability depends on the TV fork, build, installed tools and capture start.