Build Expo apps for TV

A guide for building an Expo app for an Android TV or Apple TV target.

TV development is available only in SDK 50 and later. Not all Expo features and SDK modules are available on TV. See the Limitations section for details.

React Native is supported on Android TV and Apple TV through the React Native TV project. This technology extends beyond TV, offering a comprehensive core repo fork with support for phone and TV targets, including Hermes and Fabric.

Using the React Native TV library as the react-native dependency in an Expo project, it becomes capable of targeting both mobile (Android, iOS) and TV (Android TV, Apple TV) devices.

Prerequisites

The necessary changes to the native Android and iOS files are minimal and can be automated with a config plugin if you use prebuild. Below is a list of changes made by the config plugins, which you can alternatively apply manually:

Android

• AndroidManifest.xml is modified:
  • The default phone portrait orientation is removed
  • The required intent for TV apps is added
• MainApplication.kt is modified to remove unsupported Flipper invocations

iOS

• ios/Podfile is modified to target tvOS instead of iOS
• The Xcode project is modified to target tvOS instead of iOS
• The splash screen (SplashScreen.storyboard) is modified to work on tvOS

System requirements for TV development

Android TV

• Node.js (LTS) on macOS or Linux.
• Android Studio (Iguana or later).
• In the Android Studio SDK manager, select the dropdown for the Android SDK you are using (API version 31 or later), and make sure an Android TV system image is selected for installation. (For Apple silicon, choose the ARM 64 image. Otherwise, choose the Intel x86_64 image).
• After installing the Android TV system image, create an Android TV emulator using that image (the process is the same as creating an Android phone emulator).

Apple TV

• Node.js (LTS) on macOS.
• Xcode 15 or later.
• tvOS SDK 17 or later. (This is not installed automatically with Xcode. You can install it later with xcodebuild -downloadAllPlatforms).

Quick start

The fastest way to generate a new project is described in the TV example within the Expo examples repository:

For SDK 51 and later, you can start with the TV Router example:

This creates a new project that uses Expo Router for file-based navigation, modeled after the create-expo-app default template.

Supported modules

At this time, TV applications work with the following packages and APIs listed in our Expo API docs.

• AppleAuthentication
• Application
• Audio
• Asset
• AsyncStorage
• AV
• BlurView
• BuildProperties
• Constants
• Crypto
• Device
• FileSystem
• FlashList
• Font
• Image
• KeepAwake
• LinearGradient
• Localization
• Manifests
• NetInfo
• Reanimated
• SafeAreaContext
• SplashScreen
• Svg
• Updates
• Video

TV also works with react-navigation, react-native-video, and many other commonly used third-party React Native libraries.

Limitations

• The Expo DevClient package is not supported at this time.
• The Expo Router package is only supported in SDK 51 and later.

Integration with an existing Expo project

The following walkthrough describes the steps required to modify an Expo project for TV.

{
  %%placeholder-start%%... %%placeholder-end%%
  "dependencies": {
    %%placeholder-start%%... %%placeholder-end%%
    "react-native": "npm:react-native-tvos",
    %%placeholder-start%%... %%placeholder-end%%
  },
  "expo": {
    "install": {
      "exclude": [
        "react-native"
      ]
    }
  }
}

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

{
  "cli": {
    "version": ">= 5.2.0"
  },
  "build": {
    "base": {
      "distribution": "internal",
      "ios": {
        "simulator": true
      },
      "android": {
        "buildType": "apk",
        "withoutCredentials": true
      },
      "channel": "base"
    },
    "development": {
      "extends": "base",
      "android": {
        "gradleCommand": ":app:assembleDebug"
      },
      "ios": {
        "buildConfiguration": "Debug"
      },
      "channel": "development"
    },
    "development_tv": {
      "extends": "development",
      "env": {
        "EXPO_TV": "1"
      },
      "channel": "development"
    },
    "preview": {
      "extends": "base",
      "channel": "preview"
    },
    "preview_tv": {
      "extends": "preview",
      "env": {
        "EXPO_TV": "1"
      },
      "channel": "preview"
    }
  },
  "submit": {}
}

More