React Native for Vega App Architecture
This document outlines the React Native for Vega (RNV) architecture, and serves as a reference for design choices and constraints, when building apps for Vega. See React Native Architecture documentation for more details about React Native framework.
React Native (RN) for Vega is an out-of-tree fork of React Native framework for Vega devices, and provides familiar capabilities to develop React Native apps. React Native for Vega includes support for React Native core components and APIs, as well as a set of community supported libraries most commonly used by developers. Furthermore, for TV-specific functionalities, such as focus management, React Native for Vega incorporates most of the React Native tvOS capabilities.
Architectural tenets
Parity
React Native for Vega embraces the cross-platform principles of the React Native ecosystem, and aims to provide parity with RN APIs and popular libraries. RNV supports over 80% of RN core components and APIs, and has ported over 40 RN libraries popular in the RN ecosystem, to enable reuse of code across Vega OS and other OS platforms. RNV also includes APIs from RN tvOS to support focus management and event handling capabilities specific to TV devices. Additionally, where it makes sense, RNV includes specific APIs exclusive to a specific RN platform, such as BackHandler (Android), SafeAreaView (iOS).
Furthermore, Vega SDK includes support for common RN tooling as well as additional development and testing utilities to accelerate app development while supporting a performant runtime. React Dev Tools, Chrome Dev Tool, Flashlight, and more are all available to use with RNV, and you can leverage your existing workflows with these tools to work cross-platform.
Performance
React Native for Vega is designed from the ground up to optimize for performance on Amazon devices. Your apps should meet Vega’s KPIs for performance, and our design decisions work back from these to enable you to achieve it.
RNV is built with the new architecture and benefits from all the improvements from RN core framework. This includes support for synchronous layouts and events, concurrent rendering, and fast JavaScript and native interop over JSI, including support for Turbo Modules.
The RN framework and runtime for RNV is bundled with the Vega system image, in lieu of bundling it in the app packages. The Vega lifecycle manager leverages the system bundled library to pre-warm processes which are assigned to applications for their cold start, improving the time to first frame and the overall application load time. Additionally, being a dynamically linked library, the RN runtime is kept in the shared memory space, reducing the overall system memory footprint, when multiple RN apps are running simultaneously.
RNV also supports resource pressure events that applications can handle, to efficiently manage resource utilization in their applications. Developers can ensure their apps continue to run without affecting the system performance, as well as provide uninterrupted fluid experience to their users.
Additionally, Vega's image pipeline employs smart caching to optimize in-memory and on-disk caches based on UI component usage, including visibility and mount state, to ensure low-latency frame renders. The cache's integration with the render pipeline directly manages image data in GPU memory to reduce wasted CPU cycles. RNV natively leverages Vega's image pipeline to provide a high performance image lifecycle in Vega apps.
Multi-profile and multi-modal
React Native for Vega is built to support the diverse family of Amazon devices, with different form factors, screen sizes, and supported hardware and software features. RNV includes features to enable development for TVs and smart speakers. React Native’s flex layout helps with accommodating app content to different screen sizes, while the Platform API provides runtime values for working with different uiModes supported for Vega based devices. Additionally, the Vega build tool supports customizing device profile extensions through metro bundler config that would enable compile time feature inclusion, specific to target device types.
The family of Amazon devices support different user interaction patterns through varying input modalities like voice, touch, and remote controls. RNV is built to support multi-modality out of the box, with components supporting interactions with both touch and d-pad. RNV also brings the capability of Alexa voice control and supports voice activated navigation, media control, and component interactions. Additionally, RNV includes APIs to better handle focus and remote d-pad inputs to specially tailor application experiences for TV devices.
Built on standards
React Native for Vega adopts familiar web standards for building capabilities for apps. While we’re biasing towards providing parity with the RN ecosystem APIs, we’re additionally developing core system features leveraging W3C standards. RNV’s media stack provides W3C MSE/EME APIs for media playback, and has enabled easy porting and re-use of several JS based media players - both proprietary and open source.
Additionally, RNV is building support for WebCrypto and WebWorkers which will be available in the upcoming releases. Providing standards based APIs and capabilities on Vega devices, RNV enables seamless use of JS libraries from web ecosystem.
Implementation
React Native for Vega is built as an out-of-tree implementation of React Native framework to support devices running Vega OS. RNV ported the React Native software stack including React Common, Yoga, and Hermes for Vega OS to run atop Vega’s native UI framework. RNV is built on React Native’s new architecture and only supports JSI for JavaScript to Native interfacing, along with the new Fabric renderer bringing improvements for synchronous layouts and effects, and concurrent rendering. Additionally, RNV supports native integrations through Turbo Native modules and Fabric Native components for the Vega platform.
Built into the OS, dynamically linked
RNV makes a unique architectural choice by bundling the entire React Native runtime into the Vega OS, which dynamically links with the apps at runtime. This is in contrast to the existing Vega platforms wherein the runtime is statically linked with the app binary, and bundled alongside app code.
This opinionated choice of app architecture has helped optimize on-disk storage, startup and app switch times, and memory usage on devices running Vega OS. Removing the React Native runtime reduces the app bundle size by over 10MB. Loading the runtime from the OS also enables Vega platform to pre-warm process pools with it, providing faster startup times for react native apps.
Furthermore, RNV recently introduced the ability to split the JS bundle, that removes even the React and React Native JS modules from the app’s JS bundle, further improving the application size by 1-2 MB, and ensuring compatibility with the runtime shipped with the OS. Similar to the RN runtime, the React and React Native JS bundles are also loaded and initialized at app startup alongside the application code.
API and ABI stability
The design choice of distributing the React Native runtime and a handful of libraries with the Vega OS, raises concerns around application compatibility due to occasionally introducing breaking changes in newer versions of React Native owing to the fact that RN APIs both JavaScript and Native are not stable. Furthermore, Hermes bytecode is not ABI stable, as a result JS code needs to be recompiled for each new release. All RN platforms, excluding RNV, package the react native runtime along with the app, which ensures the app will always be compatible with the RN version it built with.
In its current release, Vega OS supports RN v0.72 and plans to ship 0.76 in near future. Apps targeting a specific version of React Native runtime, would need to be aware of available RN framework versions on Vega and configure their apps to ensure the apps can install on devices where they can be supported and remains forward and backward compatible.
To mitigate this risk, RNV introduces a few configuration options to handle the potential compatibility issues.
- Package raw JS bundle in the app alongside hermes bytecode: To safeguard against future incompatibilities with newer hermes version, Vega SDK packages the raw JS bundle into the application vpkg. When newer version of hermes ships with RNV Amazon appstore will automatically recompile the JS bundle and generate new hermes bytecode when installing the app on devices with the new updates.
- NPM module version targeting: RNV provides a unique feature to target your app’s dependencies to a set selected package versions that may be available on a particular device. App developers configure their dependencies with a minimum supported dependency version as a needs entry and the latest version in the wants. This allows Appstore to make the correct device targeting to ensure apps are installed only on devices that can support the set of versions. RNV also provides a compatibility checker utility isPresentOnOS, that can, when needed, be used to check whether a specific version of a dependency is available on the device. Read more on handling Backward Compatibility.
Furthermore, the RNV team is actively working with Meta in bringing the API and ABI stability to React Native core framework. Meta just announced the first version of stable JS API for RN, and will continue to stabilize rest of the native API surface across all platforms. The work on RN stable ABI to make hermes backwards compatible, will begin soon. Upon completion, RNV would support all versions of app targeting all versions of the OS.
Versioning and upgrades
Our versioning strategy for Vega devices aims to balance customer experience, developer flexibility, and system resource management. We plan to release one new version of RNV annually, supporting up to three versions on devices with a three-year rolling window. This approach allows developers to upgrade at their own pace while ensuring app compatibility across device generations, and apps can target specific RNV version in their manifest configuration. On Vega devices only the two most recent versions will be pre-warmed to manage storage and memory constraints for optimal performance. We are working on upgrader tools to ease developer transitions between versions and minimize incremental upgrade cost. We are also exploring alternatives for developers who are unable to upgrade to newer versions within 3 years.
As an example, the new Vega device will launch in 2025 with RNV version 0.72, with support for RNV version 0.76 coming in a later release. In 2026, it would receive version 0.80, bringing the total to three versions. By 2027, when version 0.84 is released, version 0.72 would be removed from new devices to maintain the three-version rolling limit.
Last updated: Sep 30, 2025
