/react-native-tv-best-practices

Getting Started with React Native for TV

Use this reference only after stack detection identifies a react-native-tvos or Expo TV app. For Amazon Vega/Kepler or web-based TV targets, use the platform toolchain instead; do not require react-native-tvos, a tvOS Podfile, or Android TV manifest entries there.

react-native-tvos is an independent React Native fork for Apple TV, Android TV, and Fire TV. It tracks React Native core while adding TV focus, remote input, and platform APIs.

Quick Reference

• Use react-native-tvos as a drop-in replacement for react-native
• For Expo, use the TV templates or @react-native-tvos/config-tv and keep the react-native-tvos version aligned with the Expo SDK
• The fork does NOT prevent building regular iOS/Android mobile apps
• TV support adds focus handling, remote input, and TV-optimized components

Without Expo (React Native CLI)

New Project

npx @react-native-community/cli@latest init TVTest \
  --template @react-native-tvos/template-tv

Existing Project

Replace react-native in package.json:

"react-native": "npm:react-native-tvos@latest"

Android TV Setup

Add to AndroidManifest.xml:

<intent-filter>
  <category android:name="android.intent.category.LEANBACK_LAUNCHER" />
</intent-filter>

<uses-feature android:name="android.hardware.touchscreen" android:required="false" />
<uses-feature android:name="android.hardware.faketouch" android:required="false" />
<uses-feature android:name="android.software.leanback" android:required="true" />

Add these to TV-specific manifest only. Mobile builds still need touchscreen.

Apple TV Setup

• Update project.pbxproj to include tvOS platform
• In Podfile: platform :tvos, min_ios_version_supported
• Current react-native-tvos app Podfiles support either an iOS target or a tvOS target; do not keep both targets in the same Podfile

With Expo

New Project

npx create-expo-app MyTVProject -- -e with-tv
# Or with navigation:
npx create-expo-app MyTVProject -- -e with-router-tv

Existing Expo Project

1. Replace react-native:

   "react-native": "npm:react-native-tvos@0.85-stable"

2. Match the react-native-tvos version to the Expo SDK's React Native version. For SDK 56+, Expo upgrades this dependency with SDK upgrades; for SDK 55 and earlier, upgrade it manually and exclude it from expo install validation:

   "expo": { "install": { "exclude": ["react-native"] } }

3. Install TV plugin:

   npx expo install @react-native-tvos/config-tv -- --dev

4. Add to app.json:

   { "plugins": ["@react-native-tvos/config-tv"] }

5. Build. The plugin runs when EXPO_TV=1 is set, or when its isTV plugin option is true:

   export EXPO_TV=1
   npx expo prebuild --clean

Environment Setup

Same as React Native mobile, plus:

• Android: Download TV system image in SDK Manager, create Android TV emulator
• Apple TV: Install tvOS SDK via xcodebuild --downloadAllPlatforms

Key API Differences from Core React Native

Community Resources

• Ignite TV — Boilerplate from Infinite Red for TV apps
• Amazon Sample Apps — Multi-platform TV best practices
• Hoppix — Demo showing spatial navigation on TV
• @bamlab/react-tv-space-navigation — Spatial navigation across platforms

Related Skills

• setup-architecture.md — Project structure and code sharing
• setup-cross-platform.md — Handling platform differences