react-native-tvos/react-native-tvos

React Native repo with additions for Apple TV and Android TV support.

Summary

react-native-tvos is a fork of the React Native repository that adds Apple TV (tvOS) and Android TV support on top of the core codebase. It is published on npm as react-native-tvos and versioned in lockstep with React Native releases, for example 0.81.0-0 derives from React Native 0.81.0. The project targets engineers who want to ship TV apps using the React Native toolchain without losing features like Hermes or the New Architecture.

What it is useful for

The repository is useful for building React Native applications that target Apple TV, Android TV, or both, while sharing a JavaScript codebase with iOS and Android mobile apps. It adds TV-specific APIs such as Platform.isTV and Platform.isTVOS for runtime detection, plus TVEventHandler and a useTVEventHandler hook for reading remote-control input from components like a directional grid game. A TVFocusGuideView component is provided for routing D-Pad focus when focusable items are not directly in line with each other. Touchable components gain native onFocus and onBlur events, so Pressable, TouchableHighlight, and TouchableOpacity work with TV remotes with no JavaScript changes. Hermes runs on both TV targets and is enabled by default, the New Architecture (Fabric) is fully supported, and ScrollView gains a snapToAlignment="item" mode with per-item scrollSnapAlign and scrollSnapOffset props for carousels that focus and snap per item. Starting with 0.81.0-0, a precompiled React Native framework for iOS and tvOS is published via Swift Package Manager.

How engineers can use it

The README documents two paths. The Community CLI path uses a maintained template-tv:

npx @react-native-community/cli@latest init TVTest --template @react-native-tvos/template-tv
cd TVTest
npx react-native run-tvos --simulator "Apple TV"
npx react-native run-android --device tv_api_31

The template adds run-tvos, build-tvos, and log-tvos commands. To use the package directly, alias react-native in package.json to the TV fork with "react-native": "npm:react-native-tvos@latest". The README explicitly states that this package and the core react-native package cannot be used simultaneously, and warns against globally installing either, which can cause linker errors such as ld: library not found for -lPods-TestApp-tvOS. The template-tv only supports Apple TV and Android TV, and your Podfile must contain a single target. iOS and tvOS require iOS 15.1 and tvOS 15.1; Android TV requires API level 24 on later releases, or API 22 on the 0.77 line. TouchableNativeFeedback and TouchableWithoutFeedback are noted as responding to press but not to focus or blur, so they are not recommended for TV. For Expo, the README points to Expo's "Building Expo apps for TV" guide. Demos for the new APIs are available in the RNTester app, including TVEventHandlerExample.