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](../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-management.md](references/focus-management.md) | CRITICAL | Focus engines, focus guides, nextFocus*, and focus restoration | | [focus-performance.md](references/focus-performance.md) | CRITICAL | Avoiding frame drops from focus event handling | | [nav-directional.md](references/nav-directional.md) | CRITICAL | Directional navigation rules across TV platforms | | [nav-patterns.md](references/nav-patterns.md) | CRITICAL | Global/local navigation, modals, tabs, and Back behavior | | [nav-keyboard.md](references/nav-keyboard.md) | MEDIUM | Search and text input with remotes |

Design

| File | Impact | Description | |------|--------|-------------| | [design-10foot.md](references/design-10foot.md) | HIGH | 10-foot review heuristics | | [design-typography.md](references/design-typography.md) | HIGH | TV type sizing and readability | | [design-layout.md](references/design-layout.md) | HIGH | Safe areas, spacing, carousels, and focus room | | [design-color.md](references/design-color.md) | MEDIUM | Contrast and TV display color constraints |

Performance

| File | Impact | Description | |------|--------|-------------| | [perf-overview.md](references/perf-overview.md) | HIGH | TV performance targets and profiling order | | [perf-lists.md](references/perf-lists.md) | CRITICAL | Virtualized rows and poster-heavy lists | | [perf-animations.md](references/perf-animations.md) | CRITICAL | Focus and transition animation performance | | [perf-memory.md](references/perf-memory.md) | HIGH | Low-memory TV crashes and image/video pressure | | [perf-network.md](references/perf-network.md) | HIGH | Remote input, request stalls, and network resilience |

Video, Accessibility, Setup, Testing

| File | Impact | Description | |------|--------|-------------| | [video-streaming.md](references/video-streaming.md) | HIGH | TV platform protocol/DRM selection | | [video-players.md](references/video-players.md) | HIGH | Player choices and custom controls | | [video-debugging.md](references/video-debugging.md) | HIGH | Manifest, DRM, codec, and playback debugging | | [a11y-overview.md](references/a11y-overview.md) | MEDIUM | TV-specific accessibility differences | | [a11y-implementation.md](references/a11y-implementation.md) | HIGH | Accessible labels, roles, live regions, and focus | | [a11y-checklist.md](references/a11y-checklist.md) | MEDIUM | Launch accessibility audit checklist | | [setup-getting-started.md](references/setup-getting-started.md) | MEDIUM | react-native-tvos and Expo TV setup | | [setup-cross-platform.md](references/setup-cross-platform.md) | MEDIUM | Platform detection and cross-platform caveats | | [setup-architecture.md](references/setup-architecture.md) | MEDIUM | Code sharing and project structure | | [test-strategy.md](references/test-strategy.md) | MEDIUM | TV testing scope and coverage split | | [test-javascript.md](references/test-javascript.md) | MEDIUM | JS-level remote/focus test helpers | | [test-e2e.md](references/test-e2e.md) | MEDIUM | Appium and TV E2E coverage | | [release-cicd.md](references/release-cicd.md) | MEDIUM | CI, build fingerprinting, and release checks |

Problem → Skill Mapping

| Symptom | Start Here | | ------------------------------------ | ---------------------------------------------------------------------------- | | "Focus jumps to wrong element" | [focus-management.md](references/focus-management.md) → Debugging section | | "App freezes when scrolling lists" | [perf-lists.md](references/perf-lists.md) → Virtualization | | "Animations stutter on Fire TV" | [perf-animations.md](references/perf-animations.md) → Native driver | | "Text too small on TV" | [design-typography.md](references/design-typography.md) → Minimum sizes | | "Video won't play / DRM errors" | [video-streaming.md](references/video-streaming.md) → DRM section | | "Screen reader skips elements" | [a11y-implementation.md](references/a11y-implementation.md) → Roles & labels | | "Back button doesn't work right" | [nav-patterns.md](references/nav-patterns.md) → Back navigation | | "Keyboard covers content" | [nav-keyboard.md](references/nav-keyboard.md) → Built-in vs custom | | "App takes forever to start" | [perf-overview.md](references/perf-overview.md) → Startup time | | "Images causing memory crashes" | [perf-memory.md](references/perf-memory.md) → Image optimization | | "CI pipeline takes hours" | [release-cicd.md](references/release-cicd.md) → Fingerprinting | | "How to share code across platforms" | [setup-architecture.md](references/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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: callstackincubator
• Source: callstackincubator/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.