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.

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

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

Design

Performance

Video, Accessibility, Setup, Testing

Problem → Skill Mapping

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.