A production-ready TV application template built with React Native, supporting Android TV, Apple TV, Fire TV (with Fire OS), Fire TV (with Vega OS) and Web TV platforms. This monorepo showcases best practices for building cross-platform TV applications with shared UI components, efficient focus management, and platform-specific optimizations.
Note:
maintargets Vega OS 2.0 (Vega SDK 2.0). Usemainfor new development on the latest Vega platform. See the Vega 2.0 docs.
Each release branch pins a React Native version and Vega OS target. Pick the branch that matches the platform you are shipping to.
| Branch | React Native | Vega OS | When to use it |
|---|---|---|---|
main |
0.83 | 2.0 (Vega SDK 2.0) | Latest Vega OS 2.0 development. Start here for new work. |
release-rn-83 |
0.83 | 1.2 | Vega OS 1.2 devices on React Native 0.83. |
- Branches
- Features
- Architecture
- Getting Started
- Building and Running
- Development
- Project Structure
- Accessibility
- Technologies
- Contributing
- Troubleshooting
- License
- Multi-Platform Support: Single codebase running on Android TV, Apple TV, Fire TV FOS, Fire TV Vega OS and Web
- Video Playback: Integrated video player with react-native-video
- Spatial Navigation: TV-optimized focus management with React TV Space Navigation
- Remote Control Support: Native remote control integration for all TV platforms
- Drawer Navigation: Customizable left-side drawer with menu items
- Grid Layouts: Responsive content grids optimized for TV screens
- Dynamic Hero Banner: Header image that updates based on focused content
- Detail Screens: Rich content detail pages with metadata and actions
- Accessibility Settings: High contrast, larger text and reduced motion, switched on from Settings or picked up from the device (details)
- Overlay Controls: Custom video controls with spatial navigation support
- Play/pause button with visual state
- Seek bar with current time and duration display
- Exit button to return to previous screen
- Auto-hide after 5 seconds of inactivity
- Buffering Indicators: Visual feedback during video loading and seeking
- Remote Control Integration: Full support for play/pause, seek forward/backward (10s intervals), and exit
- Platform Optimizations:
- Native controls on iOS/tvOS
- Custom overlay on Android TV, Fire TV, and Web
- Hardware-accelerated rendering on Fire TV Vega with W3C Media APIs
- External Catalog API: Fetch movie content dynamically from remote JSON endpoint
- Rich Metadata Support:
- Genres, ratings, and content ratings
- Release year and duration
- Trending flags
- Multiple video source formats
- Type-Safe Transforms: Automatic conversion from catalog API format to UI-ready data structures
- Error Handling: Graceful fallback and error states for failed API requests
- Extensible: Easy to swap catalog endpoint or add new metadata fields
- Monorepo Structure: Yarn workspaces with apps and shared packages
- Shared UI Library: Reusable components across all platforms
- Platform-Specific Code: Automatic resolution of
.android.ts,.ios.ts,.kepler.tsfiles - Type Safety: Full TypeScript support with shared configurations
expo-multi-tv
- Universal application built with Expo and react-native-tvos
- Supports Android TV, Apple TV, Fire TV Fire OS, and Web
- Uses React Navigation for screen management
- Cross-platform focus management
vega
- Fire TV with Vega OS optimized build using Amazon Vega SDK
- Optimized performance for Fire TV devices
- Native remote control support via TVEventHandler
Both apps share components from the @multi-tv/shared-ui package.
This project uses a monorepo structure with Yarn workspaces to manage multiple packages and applications.
react-native-multi-tv-app-sample/
βββ apps/
β βββ expo-multi-tv/ # Universal TV app (Android TV, Apple TV, Fire TV FOS, Web)
β βββ vega/ # Fire TV Vega optimized app (Vega SDK)
βββ packages/
β βββ shared-ui/ # Shared components, screens, and navigation
βββ package.json # Workspace configuration
βββ tsconfig.base.json # Shared TypeScript configuration
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β React Native Multi-TV Monorepo β
ββββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββ€
β Apps β Packages β
ββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββ€
β expo-multi-tv β shared-ui β
β ββ Expo SDK 54 β ββ Components β
β ββ React Navigation β ββ Screens β
β ββ react-native-tvos β ββ Navigation β
β ββ Platforms: β ββ Hooks β
β β’ Android TV β ββ Theme β
β β’ Apple TV β ββ Remote Control β
β β’ Fire TV β ββ .android.ts β
β β’ Web β ββ .ios.ts β
β β ββ .kepler.ts β
β vega β β
β ββ Vega SDK β β
β ββ @amazon-devices/* β β
β ββ Platform: Vega OS β β
ββββββββββββββββββββββββββββ΄βββββββββββββββββββββββββββββββ
The @multi-tv/shared-ui package contains all reusable UI components, screens, and navigation logic. Platform-specific implementations use file extensions (.android.ts, .ios.ts, .kepler.ts) that Metro bundler automatically resolves at build time.
Before you begin, ensure you have the following installed:
- Node.js: v22.14.0 or higher (required by the Vega React Native 0.83 app)
- Yarn: v4.5.0 (configured via packageManager field)
- Platform-specific tools:
- Android TV: Android Studio with Android SDK
- Apple TV: Xcode (macOS required) with tvOS SDK
- Fire TV: Amazon Vega SDK 2.0
- Web: Modern web browser
Clone the repository and install dependencies:
# Clone the repository
git clone https://github.com/AmazonAppDev/react-native-multi-tv-app-sample.git
cd react-native-multi-tv-app-sample
# Install all dependencies
yarn installRun the universal app on different platforms:
# Android TV and Fire TV FOS
yarn dev:android
# Apple TV
yarn dev:ios
# Web
yarn dev:web
The Vega workspace uses SDK 2.0, React Native 0.83.0, and React 19.2.0. The Expo workspace uses its own Expo SDK 54 / react-native-tvos 0.81 toolchain. Use Node.js 22.14.0 or newer and a device or virtual device running Vega OS 2.0.
vega sdk install 0.24.12112
vega sdk use 0.24.12112
source ~/vega/env
vega --version
yarn install --immutable
yarn build:vega:debugKeep the checkout path free of spaces: the current Vega manifest builder invokes
an unquoted executable path and fails before bundling otherwise. Use the SDK
manager's vega command from ~/vega/bin; remove any older SDK bin directory
that takes precedence in your shell's PATH.
The Vega Babel configuration uses the React Native preset and Worklets plugin, and its manifest selects the React Native 4.x runtime. Custom native packages must support this runtime. See Amazon's migration guide.
-
Start Metro bundler:
yarn dev
-
In a new terminal, run on Android TV:
yarn dev:android
Or directly from the app directory:
cd apps/expo-multi-tv
yarn android-
Start Metro bundler:
yarn dev
-
In a new terminal, run on Apple TV:
yarn dev:ios
Or directly from the app directory:
cd apps/expo-multi-tv
yarn iosDevelopment server:
yarn dev:webOr directly from the app directory:
cd apps/expo-multi-tv
yarn webProduction build:
cd apps/expo-multi-tv
npx expo export --platform web
npx serve distFor the Fire TV optimized build:
# Development build
yarn dev:vega
# Production build
yarn build:vega
# Debug build
yarn build:vega:debugOr directly from the app directory:
cd apps/vega
yarn build| Command | Description |
|---|---|
yarn dev |
Start expo-multi-tv Metro bundler |
yarn dev:android |
Run on Android TV |
yarn dev:ios |
Run on Apple TV |
yarn dev:web |
Run on Web |
yarn dev:vega |
Start vega Metro bundler |
yarn build:vega |
Build vega for Fire TV |
yarn format |
Format code with Prettier |
yarn clean:all |
Clean all node_modules |
Navigate to the app directory first:
# expo-multi-tv
cd apps/expo-multi-tv
yarn start # Start Metro bundler
yarn android # Run on Android TV
yarn ios # Run on Apple TV
yarn web # Run on Web
yarn test # Run tests
yarn lint # Lint code
# vega
cd apps/vega
yarn start # Start Metro bundler
yarn build # Build for Fire TV
yarn test # Run tests
yarn lint # Lint codeThe monorepo contains the following packages:
Universal TV application built with Expo, supporting Android TV, Apple TV, Fire TV, and Web.
Key Technologies:
- Expo SDK 54
- React Navigation 7
- react-native-tvos
- React TV Space Navigation
Fire TV optimized application using Amazon's Vega SDK.
Key Technologies:
- Amazon Vega SDK 2.0, targeting Vega OS 2.0
- React Native 0.83.0 and React 19.2.0
- @amazon-devices packages
- Native Fire TV remote integration
- Custom navigation optimizations
Shared component library used by both applications.
Exports:
- Components:
FocusablePressable,CustomDrawerContent,MenuContext,AccessibilityProvider - Screens:
HomeScreen,DetailsScreen,PlayerScreen,ExploreScreen,TVScreen - Navigation:
DrawerNavigator,RootNavigator,AppNavigator - Hooks:
scaledPixels,useMenuContext,useAccessibility,useTheme - Theme: Centralized theming configuration, with a high-contrast preset (
createTheme,highContrastColors,contrastRatio) - Remote Control: Platform-specific remote control managers
- Develop shared components in
packages/shared-ui/src/ - Add platform-specific implementations using file extensions:
.android.tsfor Android TV.ios.tsfor Apple TV.kepler.tsfor Fire TV
- Export from
packages/shared-ui/src/index.ts - Import in apps via
@multi-tv/shared-ui
Example:
// packages/shared-ui/src/components/MyComponent.tsx
export const MyComponent = () => {
/* ... */
};
// packages/shared-ui/src/index.ts
export { MyComponent } from './components/MyComponent';
// apps/expo-multi-tv/App.tsx
import { MyComponent } from '@multi-tv/shared-ui';Any folder under packages/ with a package.json is picked up automatically by both apps' Metro configs (watched for changes and resolvable by package name), so no Metro edits are needed:
- Create
packages/my-package/package.jsonwith a scoped name and amainentry pointing at the source, for example:List{ "name": "@multi-tv/my-package", "version": "1.0.0", "private": true, "main": "src/index.ts", "peerDependencies": { "react": "*", "react-native": "*" } }reactandreact-nativeunderpeerDependencies, notdependencies(asshared-uidoes). Otherwise Yarn can install a second copy of React for the package, which causes "Invalid hook call" errors at runtime. - Add it to the apps that use it (
apps/vega/package.json,apps/expo-multi-tv/package.json):"@multi-tv/my-package": "workspace:*"
- Run
yarn installat the repo root, then import it:import { thing } from '@multi-tv/my-package';
Keep shared packages free of platform-specific dependencies where possible. Platform code belongs in .vega.tsx / .vega.ts (resolved first by the Vega Metro config), .kepler.ts, .android.ts or .ios.ts files, or in the app.
The project includes platform-specific remote control managers:
| Platform | Implementation | Technology |
|---|---|---|
| Android TV/Fire TV FOS | RemoteControlManager.android.ts |
react-native-keyevent |
| Apple TV | RemoteControlManager.ios.ts |
Native tvOS events |
| Fire TV Vega OS | RemoteControlManager.kepler.ts |
Kepler TVEventHandler |
All managers implement RemoteControlManagerInterface and integrate with react-tv-space-navigation.
The following keys are supported across all platforms in the video player:
| Key/Button | Action | Platforms |
|---|---|---|
| PlayPause | Toggle play/pause | All |
| Select/Enter | Activate focused item | All |
| Back | Exit player or go back | All |
| Left | Seek backward 10 seconds | All (in player) |
| Right | Seek forward 10 seconds | All (in player) |
| FastForward | Seek forward 10 seconds | All (in player) |
| Rewind | Seek backward 10 seconds | All (in player) |
| Up/Down | Navigate menu items | All (in navigation) |
Platform-Specific Notes:
- iOS/tvOS: Uses native video controls by default; custom overlay disabled
- Android TV/Fire TV: Custom overlay with spatial navigation for all controls
- Web: Keyboard support with arrow keys and spacebar for play/pause
- Fire TV Vega: Hardware-accelerated video with W3C Media APIs
A television is watched from three metres away, often by people who do not see as well as they used to. Settings β Accessibility (the first section of the Settings screen, reached from the cog at the bottom of the drawer) has three switches, each independent of the others:
| Switch | What changes |
|---|---|
| High contrast | Every text colour is at least 7:1 against the surface it is drawn on (WCAG AAA). Focus becomes a 6 px yellow ring around a white button with black text, so it is shown by shape as well as colour. Resting buttons and cards get a visible edge. |
| Larger text | Text drawn through the theme is 25% larger. |
| Reduce motion | Focused items no longer grow when they receive focus. |
Device settings first. The switches start from what the device reports, and follow it if it changes while the app is open (except reduce motion on Vega OS, see the table). A choice made in Settings wins over the device until the viewer chooses Use device settings.
| Setting | Android TV / Fire TV (Fire OS) | Apple TV | Fire TV (Vega OS) | Web |
|---|---|---|---|---|
| Reduce motion | AccessibilityInfo.isReduceMotionEnabled |
AccessibilityInfo.isReduceMotionEnabled |
AccessibilityInfo.isReduceMotionEnabled, read at launch only: Vega OS sends no reduceMotionChanged event, so a change made while the app runs shows after a restart |
prefers-reduced-motion |
| High contrast | AccessibilityInfo.isHighTextContrastEnabled |
Settings screen only | AccessibilityInfo.isHighTextContrastEnabled |
Settings screen only |
| Larger text | Settings screen; the system font size already scales <Text> |
same | same | same |
A platform that cannot report a setting, or whose query or listener fails, keeps the switch off. The toggles are announced as switches with their on/off state to screen readers. Like the other Settings toggles in this sample, the choices are kept in memory; persist overrides from useAccessibility() if your app needs them to survive a restart.
Using the theme in your own components. AppNavigator (and VegaAppNavigator) wrap the app in AccessibilityProvider. Read the current theme with useTheme() and build styles from it:
import { useMemo } from 'react';
import { StyleSheet, Text } from 'react-native';
import { Theme, useTheme } from '@multi-tv/shared-ui';
const createStyles = ({ colors, fontSize }: Theme) =>
StyleSheet.create({ title: { color: colors.text, fontSize: fontSize(36) } });
export function Title({ children }: { children: string }) {
const theme = useTheme();
const styles = useMemo(() => createStyles(theme), [theme]);
return <Text style={styles.title}>{children}</Text>;
}theme.focus gives the border width, ring colour, resting border colour and focus scale to use for anything focusable. FocusablePressable, the drawers, the Settings screen and the Details screen use the theme today; the Home grid and the player overlay still use the standard tokens. The contrast of every high-contrast pair is checked in apps/expo-multi-tv/__tests__/AccessibilityTheme-test.ts, so a token edited below 7:1 fails the tests.
This project is built with modern React Native and TV development tools:
| Technology | Version | Purpose |
|---|---|---|
| React Native TV (Expo) | v0.81 | Android TV, Apple TV, and web |
| React Native (Vega) | v0.83 | Fire TV Vega OS framework |
| Expo | SDK 54 | Development platform |
| TypeScript | v5.7 | Type safety |
| Yarn Workspaces | v4.5 | Monorepo management |
| React Navigation | v7 | Screen navigation |
| react-tv-space-navigation | v6.0.0-beta1 | TV focus management |
| react-native-video | Latest | Video playback |
| Amazon Vega SDK | 2.0 | Fire TV Vega OS |
Contributions are welcome! This project is an open-source sample designed to help developers build TV applications.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Run tests and linting (
yarn test:all && yarn lint:all) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Follow the existing code style
- Write tests for new features
- Update documentation as needed
- Ensure all tests pass before submitting PR
- Use conventional commit messages
Error: "can't access lexical declaration 'X' before initialization"
- This typically occurs when functions are referenced before they're defined
- Solution: Functions should be defined before useEffect hooks that reference them
Error: "No such file or directory: node"
- The Xcode build can't find the Node.js binary
- Solution: Update
apps/expo-multi-tv/ios/.xcode.env.localwith correct Node path:export NODE_BINARY=/opt/homebrew/bin/node # or your node path
- Find your node path with:
which node - Note:
.xcode.env.localis gitignored (machine-specific configuration)
Pods Installation Issues
- Clean and reinstall:
cd apps/expo-multi-tv/ios rm -rf Pods Podfile.lock pod install
Metro Bundler Port Conflicts
- If port 8081 is in use:
yarn start --port 8082
ADB Device Not Found
- Ensure Android TV/Fire TV is connected:
adb devices adb connect <device-ip>:5555
Vega SDK Not Found
- Ensure Vega SDK is installed and in PATH:
vega --versionshould print the active SDK and CLI versions (runsource ~/vega/envif not) - Check SDK path:
echo $KEPLER_SDK_HOME - Download from: Amazon Vega Developer Portal
Video Player White Screen
- Check browser console for JavaScript errors
- Ensure catalog API is accessible
- Verify video URLs are CORS-enabled
Spatial Navigation Not Working
- Use keyboard arrows for navigation on web
- Focus management requires keyboard or gamepad input
"Module not found" Errors
- Clear cache and reinstall:
yarn clean:all yarn install
TypeScript Errors
- Run type checking:
yarn typecheck
Video Playback Issues
- Verify video URLs are accessible
- Check network connectivity
- Ensure video format is supported (MP4 recommended)
This project is licensed under the MIT-0 License - see the LICENSE file for details.
- React Native TV OS - TV platform support
- React TV Space Navigation - Spatial navigation library
- Amazon Kepler Developer Portal - Fire TV development resources
- Expo Documentation - Expo SDK documentation
For questions, issues, or feature requests, please open an issue on GitHub.
Made for TV app developers
