Edit this page
A guide for building an Expo app for an Android TV or Apple TV target.
Edit this page
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.
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:
xcodebuild -downloadAllPlatforms
).The fastest way to generate a new project is described in the TV example within the Expo examples repository:
-
npx create-expo-app MyTVProject -e with-tv
For SDK 51 and later, you can start with the TV Router example:
-
npx create-expo-app MyTVProject -e with-router-tv
This creates a new project that uses Expo Router for file-based navigation, modeled after the create-expo-app default template.
At this time, TV applications work with the following packages and APIs listed in our Expo API docs.
TV also works with react-navigation, react-native-video, and many other commonly used third-party React Native libraries.
If you have an existing Expo project using SDK 50 or later, the following walkthrough describes the steps required to modify an Expo project for TV.
If you are starting with an SDK 49 project, you will need to upgrade to SDK 50 or higher before proceeding through the following steps.
1
In package.json, modify the react-native
dependency to use the TV repo, and exclude this dependency from npx expo install
version validation.
{
%%placeholder-start%%... %%placeholder-end%%
"dependencies": {
%%placeholder-start%%... %%placeholder-end%%
"react-native": "npm:react-native-tvos",
%%placeholder-start%%... %%placeholder-end%%
},
"expo": {
"install": {
"exclude": [
"react-native"
]
}
}
}
2
-
npx expo install @react-native-tvos/config-tv -- --dev
When installed, the plugin will modify the project for TV when either:
EXPO_TV
is set to 1
isTV
is set to true
Verify that this plugin appears in app.json:
{
"plugins": ["@react-native-tvos/config-tv"]
}
To see additional information on the plugin's actions during prebuild, you can set debug environment variables before running prebuild. (See also our documentation on Expo CLI environment variables.)
# See all Expo CLI and config plugin debug information
-
export DEBUG=expo:*
# See only debug information for the TV plugin
-
export DEBUG=expo:react-native-tvos:config-tv
3
Set the EXPO_TV
environment variable, and run prebuild to make the TV modifications to the project.
-
export EXPO_TV=1
-
npx expo prebuild --clean
Note: The
--clean
argument is recommended, and is required if you have existing Android and iOS directories in the project.
4
Start an Android TV emulator and use the following command to start the app on the emulator:
-
npx expo run:android
5
Run the following command to build and run the app on an Apple TV simulator:
-
npx expo run:ios
6
You can revert the changes for TV and go back to phone development by unsetting EXPO_TV
and running prebuild again:
-
unset EXPO_TV
-
npx expo prebuild --clean
7
Since the TV build can be driven by the value of an environment variable, it is easy to set up EAS Build profiles that build from the same source but target TV instead of phone.
The following example eas.json shows how to extend existing profiles (development
and preview
) to create TV profiles (development_tv
and preview_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": {}
}
A complete example is available on GitHub.