Porting Third-Party Libraries to Vega
Welcome React Native for Vega development! This guide will help you navigate the essential resources and best practices for developing libraries and services for building high-performance apps using React Native and Vega. Let’s dive into the most crucial aspects of building libraries for Vega.
By making your libraries and services Vega-compatible, you can ensure they integrate seamlessly with the platform and become available to a growing community of Vega app developers. This allows you to expand the reach and adoption of your libraries and services across Amazon devices. This article provides an overview of what you should consider when porting your library to Vega.
Supported third-party libraries
To learn more about the libraries supported on Vega today, take a look at Vega supported libraries and for supported services take a look at Vega supported services.
Remember to regularly check the official Vega documentation and our developer forum for the latest updates and best practices. If you need support and have questions please submit your questions in the Q&A section. To request any missing capabilities, please use the Feature Requests section.
Get started
As a React Native for Vega library developer it is important to first get familiar with the Vega platform and development environment.
Review Vega developer documentation
- Visit the Get Started with Vega page to understand the Vega SDK and development tools overview.
- Read React Native for Vega for an overview.
- Explore the React Native Architecture for Vega Development page to understand the design choices and constraints when building apps for Vega.
- Keep visiting the Vega SDK Release Notes to know newer versions of the SDK and offerings.
- Visit Troubleshoot Issues page to troubleshoot any issues.
Install the Vega SDK and set up development environment
- Follow the steps in the Install the Vega SDK and Developer Tools guide to download the latest Vega SDK and set up your development tools, including the Vega Studio VS Code extension.
Porting your library to Vega
Start with your library’s package.json which is a source of truth for all your dependencies. In addition to supporting Javascript/Typescript and React Native, Amazon has ported many React Native third-party libraries and supports services. Most likely your library falls into one of the library architectures called out in the Library Architecture section.
Platform-specific dependencies
As an out-of-tree platform, Vega is not implicitly compatiable with native iOS and Android libraries. Platform specific implementation has to be re-written for Vega. Vega does support standard C/C++ libraries, and other OSS libraries as long as their only dependencies are standard C/C++ libraries. See Turbo Module on how to create and build to create Turbo Modules to build out React Native bindings for React Native for Vega apps.
If your library needs Vega specific native APIs, we recommend you to use JavaScript APIs offered by Vega. These APIs are implemented using the native APIs that are not available to you at the moment. For example, if you leverage Android’s AdvertisingIdClient.getAdvertisingIdInfo() to fetch an advertising ID then on Vega you will need to use AdIdRetriever.fetchAdvertisingId().
If you require access to the native APIs, please file a request on the Vega Developer Forum.
In addition, we have ported a number of popular React Native community libraries that abstract common use cases (such as device metadata, storage) and will help speed up your development.
Library architecture
Below are the various categories of libraries based on the type of dependencies that they have. Your library mostly fall into one of the architectures discussed below. Let's take a look at a few examples for different kind of library architectures
Using JavaScript/Typescript libraries
If your library relies purely on JS/TS standard APIs and doesn’t use React Native or the platform APIs directly or transitively. These libraries should work out-of-the-box on React Native for Vega since they don’t require native linking. See the list of libraries already tested for compatibility with Vega.
React Native for Vega leverages Hermes JavaScript engine that pre-compiles JavaScript code (including libraries) into bytecode during the build process. Most pure JavaScript/TypeScript libraries without underlying platform-specific dependencies will work directly with Hermes, however some of the Hermes Features may not be supported and you should test your library for compatibility. React Native for Vega is not a browser-based environment, if your library uses Document Object Model (DOM) / Web APIs (e.g Document), you will need to look for alternatives or polyfill them for Vega.
- lodash - This is a pure JavaScript utility library without any platform-specific dependencies. This library works out-of-the-box on React Native for Vega.
- react-native-uuid - This is a pure TypeScript implementation for UUIDs without any platform-specific dependencies. This library works out-of-the-box on React Native for Vega.
Leveraging other React Native libraries
If your libraries relies on other React Native Libraries visit Supported Third-Party Libraries page to see all the available React Native for Vega and Expo libraries ported by Amazon. These libraries are scoped under “@amazon-devices”
namespace. It is important to understand how to import libraries ported by Amazon. We recommend to use Vega Module Resolver Preset (VMRP) preset instead of standard NPM aliasing to replace third-party libraries with their Vega-platform ported equivalencies. Use this preset to start using Vega for apps that already run on iOS or Android. See the page for more details.
Also see Supported Third Party services listed in the Vega developer forum. If your library relies on core React Native components and APIs (such as Platform), ensure they are supported in React Native for Vega.
Below are few examples that relies on other React Native libraries.
- launchdarkly/react-native-client-sdk- This is a pure TypeScript React Native library that provides feature Launch Darkly’s feature flag management for React Native apps. This library works-out-of-the-box on React Native for Vega with a dependency on react-native-async-storage.
Using platform-specific APIs
If your libraries relies on native code, OSS libraries or the platforms native APIs refer to Platform-specific dependencies on how to write and build Turbo Modules for native dependencies and using Platform Specific APIs.
- react-native-device-info - This is a React Native library that provides device information for React Native apps. This library has native code implementation for each platform (e.g. iOS, Android). For React Native for Vega apps, this library was ported by Amazon with a native implementation for Vega using the Vega-equivalent API to retrieve device information (such as device model, version and manufacturer).
- sentry/react-native - This is a React Native library that provides Sentry’s crash reporting and error monitoring for React Native apps. This library acts as a wrapper/bridge between React Native and Sentry’s native iOS and Android SDKs. This library did not work out-of-the-box for React Native for Vega apps, and had to ported with a Vega-specific implementation with the help of sentry-native.
- react-native-fast-image - This is a React Native library for image loading and caching in React Native apps. This library is a wrapper around the native SDWebImage (iOS) and Glide (Android) libraries. This library did not work out-of-the-box for React Native for Vega apps, and had to ported by Amazon with a native implementation for Vega using the Vega-equivalent API.
UI component libraries
If your library provides custom UI components by extending the existing React Native core components such as View or Text. Vega offers more UI components and these can be used in your libraries. Additionally your library may rely on supplementary libraries for icon sets or theming. See react-native-vector-icons and react-native-svg ported by Amazon for icons. See Platform-specific dependencies if you need to use platform native UI components directly.
- shopify-flash-list - This library provides a fast and performant list component. It is similar to FlashList provided by React Native. It uses React Native View component.
Javascript players
If your library is a media player or provides media analytics see W3C Media API. Vega offers react-native-w3cmedia as a React Native Component for playing file based and URL based media. Read that section to understand all the supported content for playback and streaming. Your library can use this API to implement your own player or collect media analytics using the API as hooks for media playback events. The following players are supported through this API. Here are the couple of examples that leverages the API to implement the players.
Testing your library
It is important to test the porting of your library for Vega thoroughly and with the latest Vega SDK releases to ensure it remains compatible with Vega. Once you are set up with Vega SDK, you can integrate your library into one of our Sample Apps to test it on Vega. Verify functional and non functional test cases. Write unit tests, component tests, snapshot tests and end-to-end tests.
Scope
Here are some of the areas to cover in your testing:
- Core functionality - Verify API functionality, performance (such as CPU and memory usage, UI fluidity), error handling and device compatibility (simulator and hardware).
- Vega SDK compatibility - Compatibility with the latest version of Vega SDK. Ensure backward compatibility for app developers running on older versions of Vega SDK.
- React Native version compatibility - Compatibility with React Native 0.72. See React Native for Vega reference for supported APIs.
- Setup and installation - Verify the package installation and setup instructions for your library. If you leverage Turbo Modules, you want to ensure build configuration and auto-linking is working as expected.
- Third-parity library conflicts - If your library has a dependency on any of the libraries listed under React Native for Vega ported libraries, use Vega Module Resolver Preset to avoid compatibility issues.
Reporting issues You can submit your questions in the Q&A section. For suspected bugs, please use the Bug Reports section.
Sample applications
You can integrate your library with one of our Sample Apps for testing. It is important to consider the differences between the Vega Virtual Device and hardware when testing your library. Follow Develop with Vega if you want get familiar on how to create a Vega application from scratch for testing your library.
If you want access an access to the device farm for testing your library on Vega devices, please submit a request on the Vega Developer Forum.
Appium
The Vega SDK supports Appium, a third-party test automation framework for native, mobile, and hybrid apps. With Appium, you can perform user interface (UI) test automation at different testing levels, which includes integration tests, end-to-end tests, and functional tests. See Appium for Vega Integration for more details.
Devoloper tooling
React Dev Tools helps you to debug and profile React component rendering in your Vega Test Applications. This is useful to debug component libraries.
CI/CD
Automating your build and deployment processes is crucial for maintaining consistent, high-quality software releases. For teams working with the Vega SDK, integrating it into your Continuous Integration (CI) pipeline can significantly streamline your development workflow. See Streamlining Development Integrating Vega SDK Into Continuous- Integration Pipelines in Vega Developer Forum.
Debugging
Visit Debug Your App and App Performance Centersections to know available tooling to debug crashes and performance issues. Though these sections are tailored to applications, these can be used for debugging your library using the test application integrated with your library. Most importantly you can use line-by-line debugging and analyze crash reports using Vega Studio. You can also inspect network traffic in Vega apps using Charles Proxy. React Dev Tools helps you to debug and profile React component rendering in your Vega Test Applications.
Distributing your library
Once your library is implemented and compatible for Vega then you should be able to publish your changes to your existing public-facing distribution mechanism. For example, to publish your package to the npm registry, see npm’s creating and publishing packages page for guidance.
We recommend you to update the library docs/README to include SOP (Standard Operating Procedure) for library maintainers/contributors and also for the applications developers on how to use the library.
Informing app developers
If you have ported your library to add support to the Vega, please submit the details here to get your library added to the Vega supported libraries and services and Supported Third-Party Libraries and Services pages. You can also post a Knowledge Base article to showcase your library and how to get started.
FAQ
- How do you create a library for React Native?
See React Native’s Create a Library page for guidance on building libraries for React Native apps. You can create a
kepler
folder for your Vega-specific code. - Which version of React Native does Vega support? React Native for Vega currently supports React Native 0.72.
- Does Vega support React Native’s New Architecture? Vega supports New Architecture - which includes Fabric and Turbo Modules.
- How can you lookup device metadata? Vega provides Platform API, Identifiers API and a port of react-native-device-info for developers to lookup device metadata.
- How can you request a new features/API for Vega? To request any missing capabilities, please use the Feature Requests section. You can also submit questions in the Q&A section to get guidance from Amazon engineers.
- How can you report suspected bugs for Vega? For suspected bugs, please use the Bug Reports section.
- Does Vega support WebCrypto API? We have a partial implementation of the WebCrypto API available through the Vega Crypto library.
- Does Vega provide a way to capture app lifecycle events? React Native's AppState API can notify you when the state of an app changes.
- Does Vega provide a way to capture video analytics? We have implemented W3C Media API in a React Native component for app developers, you can use this API as hooks for media playback events.
- How can you ensure your library remains compatible with Vega? We release a new Vega SDK versions with new features, fixes, and improvements. We recommend testing your library against each release to ensure it remains compatible with Vega.
- Are the libraries ported by Amazon scoped?
Yes. All the libraries ported by Amazon are scoped under
“@amazon-devices”
namespace. See Vega Module Resolver Preset on how to replace the default name with Vega-platform ported equivalencies.
Last updated: Sep 30, 2025