React Native Multi-TV App Sample

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.

Table of Contents

• Features
• Platform Support
• Architecture
• Getting Started
• Building and Running
• Development
• Project Structure
• Technologies
• Contributing
• Troubleshooting
• License

Features

Core Functionality

• 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

UI Components

• 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

Video Player Features

• 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

Dynamic Content Loading

• 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

Architecture

• 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.ts files
• Type Safety: Full TypeScript support with shared configurations

App Variants

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.

Architecture

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

Architecture Overview

┌─────────────────────────────────────────────────────────┐
│       React Native Multi-TV Monorepo                    │
├──────────────────────────┬──────────────────────────────┤
│ Apps                     │ Packages                     │
├──────────────────────────┼──────────────────────────────┤
│ expo-multi-tv            │ shared-ui                    │
│   ├─ Expo SDK 51         │   ├─ 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.

Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js: v18 or higher
• 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
  • Web: Modern web browser

Installation

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 install

Building and Running

Quick Start

Run the universal app on different platforms:

# Android TV and Fire TV FOS
yarn dev:android

# Apple TV
yarn dev:ios

# Web
yarn dev:web

Platform-Specific Instructions

Android TV

1. Start Metro bundler:

   yarn dev

2. In a new terminal, run on Android TV:

   yarn dev:android

Or directly from the app directory:

cd apps/expo-multi-tv
yarn android

Apple TV

1. Start Metro bundler:

   yarn dev

2. In a new terminal, run on Apple TV:

   yarn dev:ios

Or directly from the app directory:

cd apps/expo-multi-tv
yarn ios

Web

yarn dev:web

Or directly from the app directory:

cd apps/expo-multi-tv
yarn web

Fire TV (Vega)

For the Fire TV optimized build:

# Development build
yarn dev:vega

# Production build
yarn build:vega

# Debug build
yarn build:vega:debug

Or directly from the app directory:

cd apps/vega
yarn build

Available Commands

Workspace Commands

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

App-Specific Commands

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 code

Development

Project Structure

The monorepo contains the following packages:

@multi-tv/expo-multi-tv

Universal TV application built with Expo, supporting Android TV, Apple TV, Fire TV, and Web.

Key Technologies:

• Expo SDK 51
• React Navigation 6
• react-native-tvos
• React TV Space Navigation

@multi-tv/vega

Fire TV optimized application using Amazon's Vega SDK.

Key Technologies:

• Amazon Vega SDK
• @amazon-devices packages
• Native Fire TV remote integration
• Custom navigation optimizations

@multi-tv/shared-ui

Shared component library used by both applications.

Exports:

• Components: FocusablePressable, CustomDrawerContent, MenuContext
• Screens: HomeScreen, DetailsScreen, PlayerScreen, ExploreScreen, TVScreen
• Navigation: DrawerNavigator, RootNavigator, AppNavigator
• Hooks: scaledPixels, useMenuContext
• Theme: Centralized theming configuration
• Remote Control: Platform-specific remote control managers

Adding New Features

1. Develop shared components in packages/shared-ui/src/
2. Add platform-specific implementations using file extensions:
   • .android.ts for Android TV
   • .ios.ts for Apple TV
   • .kepler.ts for Fire TV
3. Export from packages/shared-ui/src/index.ts
4. 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';

Remote Control Implementation

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.

Remote Control Key Mappings

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

Technologies

This project is built with modern React Native and TV development tools:

Technology	Version	Purpose
React Native	v0.74	Core framework (tvOS fork)
Expo	SDK 51	Development platform
TypeScript	v5.3	Type safety
Yarn Workspaces	v4.5	Monorepo management
React Navigation	v6	Screen navigation
react-tv-space-navigation	v3.6	TV focus management
react-native-video	Latest	Video playback
Amazon Vega SDK	Latest	Fire TV Vega OS

Contributing

Contributions are welcome! This project is an open-source sample designed to help developers build TV applications.

How to Contribute

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and linting (yarn test:all && yarn lint:all)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Development Guidelines

• 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

Troubleshooting

iOS Build Issues

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.local with correct Node path:

  export NODE_BINARY=/opt/homebrew/bin/node  # or your node path

• Find your node path with: which node
• Note: .xcode.env.local is gitignored (machine-specific configuration)

Pods Installation Issues

• Clean and reinstall:

  cd apps/expo-multi-tv/ios
  rm -rf Pods Podfile.lock
  pod install

Android TV Build Issues

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

Fire TV Vega Issues

Vega SDK Not Found

• Ensure Vega SDK is installed and in PATH
• Check SDK path: echo $KEPLER_SDK_HOME
• Download from: Amazon Vega Developer Portal

Web Platform Issues

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

Common Issues

"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)

License

This project is licensed under the MIT-0 License - see the LICENSE file for details.

Resources

• 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

Support

For questions, issues, or feature requests, please open an issue on GitHub.

---

Made for TV app developers