React Native Tv Best Practices

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.

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

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

References

Focus and Navigation

| File | Impact | Description |

|------|--------|-------------|

| focus-management.md | CRITICAL | Focus engines, focus guides, nextFocus*, and focus restoration |

| focus-performance.md | CRITICAL | Avoiding frame drops from focus event handling |

| nav-directional.md | CRITICAL | Directional navigation rules across TV platforms |

| nav-patterns.md | CRITICAL | Global/local navigation, modals, tabs, and Back behavior |

| nav-keyboard.md | MEDIUM | Search and text input with remotes |

Design

| File | Impact | Description |

|------|--------|-------------|

| design-10foot.md | HIGH | 10-foot review heuristics |

| design-typography.md | HIGH | TV type sizing and readability |

| design-layout.md | HIGH | Safe areas, spacing, carousels, and focus room |

| design-color.md | MEDIUM | Contrast and TV display color constraints |

Performance

| File | Impact | Description |

|------|--------|-------------|

| perf-overview.md | HIGH | TV performance targets and profiling order |

| perf-lists.md | CRITICAL | Virtualized rows and poster-heavy lists |

| perf-animations.md | CRITICAL | Focus and transition animation performance |

| perf-memory.md | HIGH | Low-memory TV crashes and image/video pressure |

| perf-network.md | HIGH | Remote input, request stalls, and network resilience |

Video, Accessibility, Setup, Testing

| File | Impact | Description |

|------|--------|-------------|

| video-streaming.md | HIGH | TV platform protocol/DRM selection |

| video-players.md | HIGH | Player choices and custom controls |

| video-debugging.md | HIGH | Manifest, DRM, codec, and playback debugging |

| a11y-overview.md | MEDIUM | TV-specific accessibility differences |

| a11y-implementation.md | HIGH | Accessible labels, roles, live regions, and focus |

| a11y-checklist.md | MEDIUM | Launch accessibility audit checklist |

| setup-getting-started.md | MEDIUM | react-native-tvos and Expo TV setup |

| setup-cross-platform.md | MEDIUM | Platform detection and cross-platform caveats |

| setup-architecture.md | MEDIUM | Code sharing and project structure |

| test-strategy.md | MEDIUM | TV testing scope and coverage split |

| test-javascript.md | MEDIUM | JS-level remote/focus test helpers |

| test-e2e.md | MEDIUM | Appium and TV E2E coverage |

| release-cicd.md | MEDIUM | CI, build fingerprinting, and release checks |

Problem → Skill Mapping

| Symptom | Start Here |

| ------------------------------------ | ---------------------------------------------------------------------------- |

| "Focus jumps to wrong element" | focus-management.md → Debugging section |

| "App freezes when scrolling lists" | perf-lists.md → Virtualization |

| "Animations stutter on Fire TV" | perf-animations.md → Native driver |

| "Text too small on TV" | design-typography.md → Minimum sizes |

| "Video won't play / DRM errors" | video-streaming.md → DRM section |

| "Screen reader skips elements" | a11y-implementation.md → Roles & labels |

| "Back button doesn't work right" | nav-patterns.md → Back navigation |

| "Keyboard covers content" | nav-keyboard.md → Built-in vs custom |

| "App takes forever to start" | perf-overview.md → Startup time |

| "Images causing memory crashes" | perf-memory.md → Image optimization |

| "CI pipeline takes hours" | release-cicd.md → Fingerprinting |

| "How to share code across platforms" | setup-architecture.md → Code sharing |

Security (TV-Specific)

General dependency/input hygiene applies as in any RN app; the TV-specific deltas worth calling out:

• Never embed FairPlay/Widevine/PlayReady keys in client code — treat the license server as the trust boundary and keep DRM tokens server-issued.