React Native Tv Best Practices
CallstackOfficialPublished by Callstack
- Skill
- Guidelines
- Software development
- MIT
- No issues found
AutoGineer summary
Written by AutoGineer from the skill’s own files, not by the author
This skill provides a comprehensive set of best practices for building, testing, and debugging React Native applications on TV platforms, including Apple TV, Android TV, Fire TV, and web-based targets. It focuses on the unique challenges of the 10-foot UI, such as remote-based D-pad navigation, focus management, TV-specific performance constraints, and accessibility requirements. The guidance helps developers navigate the differences between various TV stacks like react-native-tvos and Amazon Vega/Kepler.
What it does
- Provides heuristics for 10-foot UI design, typography, and layout.
- Offers strategies for managing focus engines and D-pad navigation.
- Details performance optimization for low-memory TV hardware.
- Outlines requirements for TV-specific accessibility and screen reader support.
- Explains how to handle video playback, DRM, and player controls.
- Guides developers on identifying and setting up the correct TV platform stack.
When to use it
- When building or debugging navigation issues related to remote inputs.
- When optimizing app performance for low-memory TV devices.
- When implementing accessibility features for TV screen readers.
- When troubleshooting video playback or DRM integration errors.
- When designing layouts for 10-foot viewing distances.
Advantages
- Reduces platform-specific bugs by providing clear stack-detection rules.
- Improves user experience through consistent focus and navigation patterns.
- Helps meet accessibility standards required for TV app store approval.
- Provides actionable debugging paths for common TV-specific failures.
Usage examples
- “How do I fix focus jumping to the wrong element in my React Native TV app?”
- The agent will guide you to use focus-management.md, recommending the use of TVFocusGuideView for shared focus paths and advising against imperative focus overrides.
- “My app crashes on Fire TV when scrolling through a long list of posters. What should I check?”
- The agent will point you to perf-lists.md and perf-memory.md to implement proper virtualization and optimize image memory usage for low-memory hardware.
Install
Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/callstackincubator/react-native-tv-best-practices/downloadUnzip it into the cross-client skills folder of your project:
mkdir -p .agents/skills && unzip react-native-tv-best-practices.zip -d .agents/skills
Documentation by Callstack
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 performancenav-*: D-pad navigation, Back/Menu behavior, keyboard/search inputdesign-*: 10-foot typography, layout, color, focus visibilityperf-*: startup, memory, lists, animation, and network constraints on TV hardwarevideo-*: playback architecture, DRM/protocol selection, debugginga11y-*: TV accessibility implementation and audit checkssetup-*: stack detection, setup, architecture, cross-platform behaviortest-*andrelease-*: 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.
Files
- ATTRIBUTION.mdAdded by AutoGineer879 B
- LICENSELicence file added by AutoGineer1.1 KiB
- SKILL.md10.9 KiB
- agents/openai.yaml307 B
- references/a11y-checklist.md4.3 KiB
- references/a11y-implementation.md4.4 KiB
- references/a11y-overview.md2.8 KiB
- references/design-10foot.md3.0 KiB
- references/design-color.md3.8 KiB
- references/design-layout.md3.0 KiB
- references/design-typography.md2.6 KiB
- references/focus-management.md6.4 KiB
- references/focus-performance.md3.5 KiB
- references/nav-directional.md3.6 KiB
- references/nav-keyboard.md3.6 KiB
- references/nav-patterns.md4.4 KiB
- references/perf-animations.md3.0 KiB
- references/perf-lists.md3.3 KiB
- references/perf-memory.md2.5 KiB
- references/perf-network.md2.7 KiB
- references/perf-overview.md3.6 KiB
- references/release-cicd.md3.2 KiB
- references/setup-architecture.md3.8 KiB
- references/setup-cross-platform.md3.3 KiB
- references/setup-getting-started.md5.1 KiB
- references/test-e2e.md3.6 KiB
- references/test-javascript.md3.7 KiB
- references/test-strategy.md2.3 KiB
- references/video-debugging.md1.6 KiB
- references/video-players.md3.2 KiB
- references/video-streaming.md2.1 KiB
references/perf-memory.md
title: Memory Management on TV impact: HIGH tags: memory, ram, image-optimization, garbage-collection, tv-performance
Memory Management on TV
On TVs, you're sharing RAM with the OS, video decoder, DRM, audio buffers, and even the live TV tuner. Your UI runs in the leftovers.
Quick Reference
Many devices have 1-1.5 GB total — your app might only get 300-500 MB
4K video streams eat 100-200 MB just for decoded frames
Poster/backdrop caches are the biggest UI-side memory lever
Smart TVs aggressively reclaim memory from your app
Symptoms of Memory Pressure
Sudden GC spikes (frame drops during scrolling)
Images unloading from cache and re-downloading mid-session
Crashes or forced restarts (Tizen and webOS are notorious)
Image Memory Optimization
Bad:
<Image source={{ uri: posterUrl }} />Without cache control, changing posterUrl holds multiple decoded bitmaps until GC runs.
Better:
<Image
source={{ uri: posterUrl, cache: 'force-cache' }}
resizeMode="cover"
/>Or use react-native-fast-image for cache control.
List Item Memory
Even with virtualization, if row components keep large objects in state (full metadata blobs), you're holding memory hostage.
Better: Store only IDs in list item state, fetch full details on demand.
TV-Specific Checks
Match asset size to display size — A decoded 4K backdrop for a small thumbnail wastes the same memory as a visible full-screen asset.
Measure with video mounted — UI memory that looks fine without playback can fail once decoded frames and DRM buffers exist.
Keep cache pressure visible — Watch for poster eviction/re-download loops during fast row navigation.
Avoid large list item state — Keep IDs in rows; fetch full metadata on demand.
Use native profiling tools:
Android TV/Fire TV: Android Studio Profiler → Memory tab
Apple TV: Xcode Instruments → Allocations + Leaks
Tizen/webOS: Emulator memory usage overlays
Platform Quirks
Low-end Fire TV: ~0.5-1 GB RAM total. Every extra library adds startup time.
Tizen/webOS: Aggressive OS memory reclaim — your app can be killed without warning.
Apple TV 4K: More generous RAM (4 GB) but don't assume you can skip optimization.
Related Skills
perf-overview.md — Overall performance strategy
perf-lists.md — Virtualized lists reduce memory
perf-network.md — Caching and payload optimization
Requirements and compatibility
Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta
“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.
Security
No issues found by our static scan· No issues found
A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.
Attribution and licence
- Published by
- Callstack
- Publisher
- Callstack (Official)
- Source
- callstackincubator/agent-skills · skills/react-native-tv-best-practices · commit 59e9d17
- Licence
- MIT License (redistribution allowed)
- LICENSE (added by AutoGineer from LICENSE)
- ATTRIBUTION.md (written by AutoGineer)
- Synced
AutoGineer is not affiliated with or endorsed by Callstack.
Related skills
Web Artifacts Builder
AnthropicOfficial
A structured workflow for developing and bundling complex, multi-component React artifacts for Claude.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreApache-2.0Medium riskHas scriptsGitHub stars of the source repository188.6k
Frontend UI Engineering
Addy Osmani· Community
Engineering standards for building accessible, responsive, and production-ready frontend user interfaces.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreMITGitHub stars of the source repository113.9k
Ask Sonner
Emil Kowalski· Community
A comprehensive guide for implementing, styling, and troubleshooting the Sonner toast notification library in React applications.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreMITGitHub stars of the source repository54.3k
Pick UI Library
Emil Kowalski· Community
Get recommendations for frontend UI libraries based on a curated, opinionated list.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreMITGitHub stars of the source repository54.3k
Animate Expo
Emil Kowalski· Community
A senior mobile engineering guide for building React Native and Expo animations that feel correct on real devices.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreMITGitHub stars of the source repository54.3k
Prototype
Emil Kowalski· Community
A design engineering workflow for building and comparing distinct UI variants using an isolated picker harness.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreMITGitHub stars of the source repository54.3k
Download ZIP
The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download react-native-tv-best-practices.zip