/react-native-tv-best-practices

name: react-native-tv-best-practices
description: Reviews React Native TV apps for focus/D-pad navigation, 10-foot UI layout, TV playback/DRM integration, low-memory TV performance, and TV accessibility. Use when building, debugging, or reviewing react-native-tvos, Expo TV, Amazon Vega/Kepler, or React Native web TV targets where the issue depends on remote input, TV focus, TV packaging, TV hardware, or TV playback constraints.
license: MIT

React Native TV Best Practices

Overview

TV-specific review guidance for React Native-backed apps on Apple TV, Android TV, Fire TV, Amazon Vega/Kepler, and web-based TV targets such as Tizen or webOS.

Use this skill only for TV deltas: remote input, focus engines, 10-foot layout, platform packaging, playback/DRM, low-memory TV hardware, and TV accessibility. For ordinary React Native performance or architecture issues, use [react-native-best-practices](../react-native-best-practices/SKILL.md).

Skill Format

Reference files are grouped by topic prefix:

• `focus-*`: focus engines, focus guides, focus event performance
• `nav-*`: D-pad navigation, Back/Menu behavior, keyboard/search input
• `design-*`: 10-foot typography, layout, color, focus visibility
• `perf-*`: startup, memory, lists, animation, and network constraints on TV hardware
• `video-*`: playback architecture, DRM/protocol selection, debugging
• `a11y-*`: TV accessibility implementation and audit checks
• `setup-*`: stack detection, setup, architecture, cross-platform behavior
• `test-*` and `release-*`: test coverage, E2E, and CI/release workflows

When to Apply

Apply this skill when the app targets a TV platform and the work involves:

• Focus movement, visible focus, focus restoration, or remote/D-pad input
• TV layout readability, overscan/safe areas, or 10-foot UI density
• TV player controls, manifests, DRM, decoder support, or playback errors
• Performance on low-memory TV hardware, especially with video or large carousels
• TV accessibility with screen readers, captions, focus order, or remote-only interaction
• Platform setup for `react-native-tvos`, Expo TV, Amazon Vega/Kepler, Tizen, or webOS

Before You Start — Identify the TV Stack

This skill covers several TV stacks. **Detect which one the app targets before flagging setup issues** — demanding `react-native-tvos`, a tvOS Podfile, or an Android TV manifest on a Vega/Kepler or web-based TV app produces false positives.

| Stack | How to detect | Setup expectations | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | **react-native-tvos** (Apple TV, Android TV, Fire TV) | `"react-native": "npm:react-native-tvos@…"` in package.json | tvOS Podfile (`platform :tvos`); Android TV `leanback`/`LEANBACK_LAUNCHER` manifest entries; TV emulator/simulator | | **Expo + react-native-tvos** | above **plus** `@react-native-tvos/config-tv` in app.json | `EXPO_TV=1` prebuild; `react-native-tvos` version must match the Expo SDK; not all Expo features/libraries are available on TV | | **Amazon Vega / Kepler** | Vega/Kepler SDK & tooling (`@amazon-devices/*` deps, Kepler manifest); **no** `react-native-tvos` | Amazon's Vega/Kepler toolchain — `react-native-tvos`, tvOS Podfile, and Android TV manifest do **not** apply | | **Web-based TV** (Tizen, webOS) | web bundler (Rsbuild/webpack) + platform packaging; spatial-nav library | Platform SDK packaging; `@noriginmedia/norigin-spatial-navigation` for focus |

The focus, 10-foot design, performance, accessibility, and player guidance applies across all of these — only the **setup/build** expectations are stack-specific.

Review Rules

• Resolve the target stack before setup advice.
• Prefer natural focus order and focus guides before imperative focus calls or broad `nextFocus*` maps.
• Treat focus loss, invisible focus, and broken Back/Menu behavior as navigation bugs.
• Check readability, safe areas, and focus states at TV distance before tuning visual details.
• Profile on the weakest supported TV device before reporting performance fixes as complete.
• Separate playback failures by layer: manifest request, DRM license exchange, decoder capability, player state, and React UI controls.

Priority-Ordered Guidelines

| Priority | Category | Impact | Prefix | |----------|----------|--------|--------| | 1 | Focus and D-pad navigation | CRITICAL | `focus-*`, `nav-*` | | 2 | List, animation, and input performance | CRITICAL | `perf-*` | | 3 | Playback and DRM failures | HIGH | `video-*` | | 4 | 10-foot readability and layout | HIGH | `design-*` | | 5 | TV accessibility | HIGH | `a11y-*` | | 6 | Stack setup, testing, and release | MEDIUM | `setup-*`, `test-*`, `release-*` |

Quick Reference

1. Detect the TV stack from package files, manifests, native folders, and platform tooling. 2. Reproduce navigation with the remote or D-pad path, not mouse/touch assumptions. 3. Confirm the focused element is always visible, reachable, and restored after modals/routes. 4. Check playback failures from the network/DRM layer upward before changing React controls. 5. Measure list, animation, memory, and startup work on the weakest supported TV target.

References

Focus and Navigation

| File | Impact | Description | |------|--------|-------------| | [focus-