Rate your experience with the Vega SDK
Vega SDK and OS version 2.0
Vega SDK 2.0, Vega OS 2.0, and the Vega Developer Tools are now generally available, and they’re no longer in open beta. Vega OS 2.0 has rolled out to all Vega-powered Fire TV devices, so you can build for OS 2.0 today. Vega 2.0 enables you to:- Build faster, more responsive apps with React Native 0.83. React Native 0.83 is now generally available and brings React 19, the React Compiler, and Hermes v1. The React Compiler handles memoization at build time, so you no longer need to add
React.memooruseCallbackby hand. Debug performance issues with React Native DevTools. Style focus states with new CSS properties such asboxShadowandoutline. Since SDK 0.24, more libraries support RN 0.83. These include React Navigation, Reanimated, and Lottie, plus additional Expo libraries. - Add native capabilities to your React Native app. Use Vega native APIs to build custom UI components in C++ and to schedule background tasks that run after your app closes. Build the rest of your app in React Native. Native tooling is in open beta.
- Migrate and build with AI assistance. Amazon Devices Builder Tools (ADBT) for AI is the recommended way to use AI coding agents for Vega development. Use it to plan your upgrade from RN 0.72 to RN 0.83, migrate a Fire OS app to React Native for Vega, and debug performance issues.
- Catch compatibility issues before you build.
vega project doctornow includes compatibility linters for JavaScript, TypeScript, and native code. They flag APIs that aren’t available on every OS version your app targets.
Announcements
Vega general availability and API stability
Starting with 2.0, the Vega API surface stays stable across minor SDK releases. Breaking changes ship only in the major release, once a year. Minor releases follow on a regular cadence. You can adopt each minor release without rework, and plan for major upgrades on your own timeline.OS version range support
Your app’s manifest can now declare a range of supported OS versions, from a minimum to a target. Most Vega devices update to the latest OS version, so for most apps, set bothmin and target to 2.0. In future releases, some devices might not receive the latest OS version. If your app needs to reach those devices, set min to the oldest OS version you support, and use the compatibility linters to guard newer APIs.
Action required: Set [os.version] in manifest.toml to the range your app supports, then rebuild.
See Target OS Versions
TextInput Done and Back behavior will match stock React Native
In an upcoming Vega OS release, a single-lineTextInput on React Native 0.83 without submitBehavior will use the React Native default, blurAndSubmit. Pressing Done will fire onSubmitEditing, then blur the field and close the keyboard. Pressing Back will fire onSubmitEditing with submitAction set to 'previous', then do the same. Today, the field keeps focus after Done, and Back closes the keyboard without notifying your app. Fields that set submitBehavior="submit", multiline fields, and React Native 0.72 apps aren’t affected.
Action required: If your RN 0.83 app treats every onSubmitEditing event as a submission, filter on submitAction and treat 'previous' as a dismiss. To keep the keyboard open after Done, set submitBehavior="submit". For details, see Handle Password Input Events.
Breaking changes
OS version module entries are now generated at build time
In SDK 0.24,vega project update-manifest wrote /com.amazon.vega.os@IVega_* entries into the [[needs.module]] and [[wants.module]] sections of your source manifest.toml. Starting with SDK 2.0, the build owns these entries and generates them from [os.version] into the packaged manifest. vega project update-manifest now writes only the min and target values, and on every run it removes tool-owned module entries from your source manifest. Module entries you declare for other system modules are preserved.
On a project created with SDK 0.24, the first run deletes these lines from your source-controlled manifest:
Deep imports no longer resolve in React Native 0.83 libraries
Starting with SDK 2.0, the React Native for Vega core package and the Vega versions of Gesture Handler, Lottie, React Navigation, Reanimated, React Native SVG, and React Native Screens expose only their public JavaScript interface innode_modules. The public API is unchanged. If your RN 0.83 app uses top-level imports, it’s unaffected. If it uses deep imports that reach into a library’s internal implementation paths, your build fails because those paths no longer resolve. This change doesn’t affect RN 0.72 apps.
Action required: If your RN 0.83 app uses deep imports, replace them with top-level imports (preferred) or lazy imports. If any of your Jest tests depend on a library’s internal implementation, mock those modules in your test code instead.
React Linear Gradient is replaced by a built-in style prop in React Native 0.83
React Native 0.83 supports linear gradients natively through theexperimental_backgroundImage style prop, which accepts standard CSS linear-gradient() syntax on any View. The @amazon-devices/react-linear-gradient library is no longer needed and isn’t included in the RN 0.83 library set. RN 0.72 apps are unaffected.
@amazon-devices/react-linear-gradient dependency and replace <LinearGradient> components with the experimental_backgroundImage style prop on a View.
See Replace LinearGradient with the backgroundImage style prop
Use @shopify/flash-list instead of @amazon-devices/shopify__flash-list in React Native 0.83
On React Native 0.72, Vega provided its own FlashList implementation as@amazon-devices/shopify__flash-list. On React Native 0.83, use the public FlashList package, @shopify/flash-list, instead. The @amazon-devices/shopify__flash-list package isn’t available for React Native 0.83 apps, so an app that still imports it fails at runtime. RN 0.72 apps are unaffected.
Action required: When you migrate to RN 0.83, replace the @amazon-devices/shopify__flash-list dependency with @shopify/flash-list, and update your imports.
Experimental APIs are no longer supported
SDK 0.24 announced that the Vega SDK’s experimental APIs were being deprecated. Starting with SDK 2.0, experimental APIs are no longer supported. Action required: If your app uses experimental APIs, migrate to the supported APIs before you build with SDK 2.0. To find the experimental APIs in your app and plan the migration, use Amazon Devices Builder Tools (ADBT) for AI version 1.0.19 or later.New features
Build native UI components and background tasks in C++
React Native for Vega apps can now include views and modules written in C++, and use them from JavaScript like any other component or module. Two sample apps for React Native 0.83 show how. Both run on Fire TV Stick and the Vega Virtual Device:- Native UI Component sample: Renders C++ views built with the Vega UI toolkit inside your React tree. The sample passes props from JavaScript to native code and sends events back to JavaScript. It also covers D-pad focus, animation, image prefetching, and VoiceView accessibility.
- Periodic Background Task sample: Wraps the Vega Task Manager in a C++ Turbo Module, so your app can run a headless JavaScript task on a repeating schedule. The schedule stays in place after your app closes. The minimum interval is 60 seconds, and each run can take up to five minutes.
PeriodicTasks Turbo Module into your app.
Read more in the Enhance your React Native App with Vega native APIs blog post.
Find and fix accessibility issues as you edit in Vega Studio
The A11y Inspector in Vega Studio checks your .tsx and .jsx files as you edit. It flags components that assistive technologies, such as VoiceView, can’t describe or operate, and suggests quick fixes. The inspector uses the same rules as the Vega ESLint plugin, so its results match your build pipeline. It’s on by default in Vega Studio 0.24.2 and later. See Find and Fix Accessibility Issues in Vega StudioCompatibility lint for JavaScript and TypeScript
Whenmin is lower than target, an API introduced after min might not exist on every device your app supports. vega project doctor now checks your source code against the SDK compatibility manifest and reports three rules:
no-unguarded-os-api(error): an API introduced afterminis used without a guard.no-removed-api(error): an API removed at or beforeminis still in use.warn-deprecated-api(warning): an API deprecated at or beforetargetis still in use.
isPresentOnOS() check from @amazon-devices/kepler-compatibility and provide a fallback, or raise min. The second argument to isPresentOnOS() is the library version that provides the API, not the OS version. vega project doctor exits with a non-zero status when a check fails, so you can use it as a gate in your CI pipeline.
Compatibility lint for native code
For projects withkepler.projectType set to native, vega project doctor also checks C and C++ sources. It reports unguarded QueryInterface calls for OmniKit interfaces added after min, and interfaces removed before min or deprecated by target. To use an optional newer interface, call TryQueryInterface<T>() and check for nullptr. Use QueryInterface<T>() only for interfaces guaranteed at min.
See Upgrade Your App’s OS Version Compatibility
Verify Account Login integration from the command line
The newkcp-cli-v2 tool, pre-installed on Vega devices, lets you check your app’s Content Launcher Account Login status without a separate test harness. From your app’s component shell, run kcp-cli-v2 account-login read-status to read the current login status. Run kcp-cli-v2 account-login watch-status to monitor login status changes in real time while you sign in and out of your app. The tool requires Developer Mode and a sideloaded app, and doesn’t run on the Vega Virtual Device.
See Test Content Launcher Integration
Improvements
Full TextPath support in React Native SVG
@amazon-devices/react-native-svg now fully supports the TextPath element, so you can render text along a curved or arbitrary path, for example for circular labels and curved headings, without pre-rendering the text as an image.
See react-native-svg
Smoother audio across MSE segment boundaries
The W3C Media pipeline now implements the Media Source Extensions audio splice algorithm and handles overlapping audio frames. Before this change, adaptive streams that appended overlapping or padded audio segments, such as at ad insertion points or period boundaries, could produce audible clicks, gaps, or drift. Decoded (PCM) audio is now trimmed and linearized before it reaches the audio sink, so playback stays continuous across segment boundaries without any change to your app. See W3C Media API in React Native for VegaResolved issues
AC-3 and E-AC-3 codec strings in W3C Media capability checks
navigator.mediaCapabilities.decodingInfo() no longer rejects configurations that use the ac3, eac3, or ec3 codec strings. Before this fix, these strings were routed to the AV1 codec parser, so the call failed and players such as Shaka Player filtered out every variant with AC-3 audio. Separately, an MPEG-TS SourceBuffer with a combined codec string such as video/mp2t; codecs="avc1.4D401F,ac3" played video but silently dropped the AC-3 audio track. These streams now use a demuxer that supports AC-3 in MPEG-TS, so audio plays.
dash.js stability fix in dash-rel-v5.0.0-r1.8
The Vega release of dash.js includes the following fix:- dash.js now reports an error once, when the retry limit is reached, instead of on every retry. This matches the behavior of upstream dash.js 5.0.0.
Video surface resize while playback is paused
When you resized a video surface while playback was paused, the paused frame didn’t scale to the new size, or the video briefly appeared in the wrong position before it resumed. The compositor now re-presents the last frame at the new size, so picture-in-picture and multiview layouts resize correctly in the paused state.Seek events in MSSE mode
Native apps that use Media Source Sample Extensions (MSSE) mode didn’t receive theseeked event after a call to seek() on IMediaSampleSourceTrack. The media pipeline now registers its seek-completion callback, so IHtmlMediaElementEventListener receives timeupdate and seeked when a seek completes. In MSSE mode, seek() is asynchronous.
TextInput cursor position after focus changes
When aTextInput sat next to another focusable element, moving focus away with the D-pad and back moved the cursor one character each time. The key-up event from the D-pad press reached the TextInput after focus had already moved. The cursor now stays where you left it.
vpm install-async exits after installation
vpm install-async printed INSTALLATION_COMPLETED but didn’t exit when you ran it without the --token argument, which blocked automated test scripts. The command now exits when installation finishes. If you added --token as a workaround, you can remove it.
W3C Media API reference formatting
The W3C Media API reference now renders type links and multi-line descriptions correctly. This affectsMediaCapabilitiesKeySystemConfiguration, the scalingmode property of VideoProps, HTMLVideoElement, and AudioPlayer.
Appium tests work again on OS 1.2 and later
On some OS 1.2 builds, the automation toolkit service that Appium uses didn’t start on the device. Port 8383 showed as listening, but no process handled requests. Appium commands such asfindElement, takeScreenshot, and getPageSource failed with socket hang up or ECONNRESET, and re-enabling Developer Mode didn’t help. The automation toolkit service now starts in Developer Mode, so Appium sessions connect and run as expected.
Known issues
RN 0.83 apps crash at launch when a dependency pulls in the RN 0.72 runtime
If an RN 0.83 app depends on a library version built for RN 0.72, the RN 0.72 runtime loads into the same process and the app crashes at launch withSIGABRT or SIGSEGV. The device log shows Failed to get system bundle path for: index.amzn__react-native-kepler-2.hermes.bundle. The most common cause is @amazon-devices/kepler-ui-components 2.x, which depends on @amazon-devices/keplerscript-native-ui-components and its bundled RN 0.72 runtime.
Workaround: Upgrade @amazon-devices/kepler-ui-components to 3.0.0 or later. Replace @amazon-devices/react-linear-gradient with the experimental_backgroundImage style prop (see Replace LinearGradient with the backgroundImage style prop). After a clean rebuild, check that keplerscript-app-config.json doesn’t list any RN 0.72 system bundles.
HEVC playback fails on Fire TV Stick HD (2026)
On Fire TV Stick HD (2026) running OS 2.0, the HEVC hardware decoder isn’t available. HEVC streams load indefinitely without an error event, andKeplerMediaDescriptor.queryMediaCapabilitiesSync() returns no decoders for CodecMimeType.MIME_HEVC. H.264 playback isn’t affected.
Workaround: Before playback, query KeplerMediaDescriptor for HEVC support and fall back to an H.264 stream when no decoder is returned.
No error event when a video decoder can’t be created
If the media pipeline can’t create or link a video decoder, it doesn’t send anerror event to JavaScript. Playback appears to load indefinitely. To detect unsupported codecs before playback, use KeplerMediaDescriptor.queryMediaCapabilities().
HEVC live HLS in MPEG-TS doesn’t start
Live HLS streams that carry HEVC video in MPEG-TS segments don’t show video. The timestamp offset is applied twice, so samples get negative timestamps and are dropped, and Shaka Player repeatedly seeks forward. H.264 streams and HEVC VOD streams aren’t affected. Workaround: In Shaka Player, setmanifest.hls.sequenceMode to true.
removeSourceBuffer() hangs while an append is in progress
If you callMediaSource.removeSourceBuffer() while appendBuffer() is still in progress on that SourceBuffer, the call blocks the JavaScript thread and the system stops the app as not responding. The call doesn’t throw an InvalidStateError.
Workaround: Before you remove a SourceBuffer, check that its updating property is false, or wait for its updateend event.
Video surface ignores pixel aspect ratio
KeplerVideoSurfaceView renders decoded frames with square pixels and ignores the stream’s pixel aspect ratio. Anamorphic standard-definition content, such as 720×576 broadcast video with a 16:9 display aspect ratio, appears horizontally squeezed. All scalingmode values, including strech, preserve the buffer’s aspect ratio, so you can’t correct the aspect ratio in your app.
Large multi-period DASH manifests can make dash.js apps stop responding
The native XML parser is available only for Shaka Player, so dash.js parses manifests in JavaScript. Live DVR streams that add a period for each ad break grow on every manifest refresh. After about 25–60 minutes, a single refresh can block the JavaScript thread long enough that the system stops the app as not responding. Workaround: Run the player in a headless JavaScript service so manifest processing doesn’t block the UI thread. Don’t log orJSON.stringify the full manifest in your app.
HMAC keys must be exactly 256 bits
WebCrypto.subtle.importKey() in @amazon-devices/keplercrypto rejects HMAC-SHA-256 keys that aren’t exactly 256 bits long, with NotSupportedError: A key length greater than the hash length (256 bits) is not supported.
Workaround: For keys longer than 512 bits, hash the key with SHA-256 before you import it. This produces the same HMAC result. For other key lengths, use another HMAC implementation until the fix ships.
Screensaver starts during gameplay with a phone controller
The screensaver starts after five minutes without local input, even when a user plays a cloud-streamed game with a paired phone as the controller. Input from the phone goes to the cloud session, so the device doesn’t register user activity. Vega doesn’t provide an API to keep the screen on.Apps can’t change the display refresh rate
State-changingDisplayManager APIs, such as requestConfigChange() and enableAutoConfigSwitch(), require the com.amazon.graphics.privilege.display.manager privilege, which isn’t available to third-party apps. Without it, commitStates() returns a commit ID but makes no change and doesn’t call onCommitSuccess or onCommitFailure. Apps can’t switch the output to match content frame rates such as 23.976 or 50 fps.
”Alexa, previous” doesn’t reach the app
When a user says “Alexa, previous” during playback, the app’s Media Playback handler doesn’t receive the Previous command, and Alexa replies that the command isn’t working. “Alexa, next” and “Alexa, pause” work as expected.VPN Manager doesn’t route IPv6 traffic
The VPN Manager API supports WireGuard only and doesn’t route IPv6 traffic through the tunnel. IPv6 traffic leaves the device outside the VPN, andaddRoute() rejects IPv6 CIDRs with Invalid route CIDR format. IPv6 support is planned for a future release.
PNG splash screen animations play at a low frame rate
Splash screen animations made of many full-HD PNG frames play at about 8 fps and can take several seconds to appear. The device decodes each PNG on the CPU. Workaround: Encode the frames as ASTC and package them ascompressedSplashScreenImages.zip next to SplashScreenImages.zip in assets/raw/. ASTC splash animations play at 30 fps. In this release, an ASTC splash screen can render black on every launch after the first until the device restarts.
Crash reporting libraries can’t capture low-memory kills
When the kernel stops an app for exceeding its memory limit, the process receivesSIGKILL, so crash reporting libraries such as Sentry can’t record the crash. tryGetLastTerminationData() currently reports only app-not-responding terminations.
VoiceView can’t be enabled from the Developer Mode shell
vdcm set "com.amazon.devconf/system/accessibility/VoiceViewEnabled" "ENABLED" fails with No permission for operation in the Developer Mode shell. To turn on VoiceView, use the device’s accessibility settings instead.
ifconfig doesn’t work in the Developer Mode shell
The Developer Mode shell doesn’t have access to/proc/net, so ifconfig doesn’t return network information. To find your device’s IP address for VDA over TCP/IP, select Settings > Network on the device.
TypeScript 4 projects fail to build with @types/node 26
If your project uses TypeScript 4 and installs@types/node 26.x, directly or through another dependency, type checking and builds fail with errors in the @types/node declaration files. @types/node 26.x uses TypeScript syntax that TypeScript 4 doesn’t support.
@types/node is a community-maintained package that isn’t part of the Vega SDK. The Vega SDK doesn’t set your @types/node version, so this issue can affect a project on any SDK version.
Workaround: Update typescript in your devDependencies to version 5, for example 5.8.3. If you can’t upgrade TypeScript yet, pin @types/node to a version earlier than 26 in devDependencies or overrides. Then run npm install and rebuild.
