How to Use React Native Libraries in Your Vega App

Vega is Amazon’s Linux-based operating system for Fire TV.

It uses a fork of React Native (React Native for Vega), so not all RN libraries work out of the box. That means if you are porting your app to Vega, you may need to wire in a Vega fork of some of your libraries as well.

The good news is that we have ported many of the most popular libraries used in TV apps, and we’ve also built the Vega Module Resolver Preset (VMRP), which replaces third-party libraries with their Vega-platform ported equivalencies.

Let’s break it down with the four categories of libraries for Vega:

1. Libraries with Vega forks
2. Libraries that depend on another forked library
3. Libraries that work out of the box
4. Libraries that don’t work with Vega yet

Libraries with Vega forks

Libraries with Vega forks work natively in your Vega app. You can find a list of them in the documentation. They are supported as part of the @amazon-devices/ namespace.

There are two ways to use a forked library:

1. Import the fork directly by its @amazon-devices/ name. Install the fork:

npm install @amazon-devices/[email protected]

Enter fullscreen mode Exit fullscreen mode

Then import it using the @amazon-devices/ prefix:

import { ... } from '@amazon-devices/react-native-gesture-handler'

Enter fullscreen mode Exit fullscreen mode

This works for your own code, but it won’t help with transitive imports. If another library in your dependency tree imports react-native-gesture-handler by its original name, that import won’t be redirected and will break at runtime. For that reason, option 2 below is recommended for most apps.

2. Keep your original import names by using the VMRP, which swaps the original library for the fork at bundle time. See How to use the Vega Module Resolver Preset below for the setup steps and an explanation of how it works.

The VMRP keeps your import statements platform-neutral and handles transitive dependencies inside other libraries automatically.

Check the Supported Libraries and Services documentation for more information and a complete list of the natively forked libraries.

Libraries that depend on another forked library

A lot of libraries rely on other libraries to work. For example, react-native-chart-kit relies on react-native-svg to work.

These libraries won’t work on Vega on their own, they have internal imports of the original package that need to be redirected to the Vega fork via VMRP.

Simply adding @amazon-devices/react-native-svg to your package.json does not redirect that internal import because Metro still tries to resolve the string react-native-svg, and the build breaks. You’ll need to use the VMRP (see How to use the Vega Module Resolver Preset below), because it rewrites imports inside libraries you can’t modify.

Install the parent library, and then install both the fork and its upstream at their exact pinned versions:

npm install [email protected]
npm install --save-exact [email protected]
npm install @amazon-devices/[email protected]

Enter fullscreen mode Exit fullscreen mode

Your dependencies will then look like:

 "dependencies": {
     ...
     "@amazon-devices/react-native-svg": "2.0.1759135970",
     "react-native-svg": "13.14.0",
     "react-native-chart-kit": "~7.0.1",
     ...
}

Enter fullscreen mode Exit fullscreen mode

You’ll need to include both the @amazon-devices/ version and the upstream version of the dependency. The fork provides the native implementation, and the plain package must be present at the exact version the fork aliases so the VMRP can map it. (Only the aliased library needs an exact pin, the parent library can use a normal version range.)

Libraries that work out of the box

The simplest libraries are the ones that already work with Vega, no porting required. These are pure JavaScript libraries with no native module code. They don’t touch any platform-native layer, so they run on React Native for Vega the same way they run on standard React Native. Just import them like you normally would.

Libraries that don’t work with Vega yet

Finally, there are the libraries that aren’t available on Vega yet.

Tell us which ones you would like to see come to Vega!

We’re working on making Vega better every day, and that includes porting the libraries you’d like to see.

How to use the Vega Module Resolver Preset

The VMRP is a Babel preset (built on babel-plugin-module-resolver) that rewrites import specifiers at bundle time. It scans your node_modules for @amazon-devices/ packages, reads their alias target (the upstream package name and exact version they replace), and rewrites every matching import specifier to point at the fork instead. Because the rewrite happens during transpilation, it applies to all code Metro bundles, including imports inside third-party libraries you can’t edit.

This is why both packages must be installed: the upstream provides the module specifier that existing code references, and the fork provides the native implementation that VMRP redirects to. The pattern is similar to how monorepo workspaces alias packages: two copies coexist in node_modules and a resolver layer decides which one gets loaded, except here it’s a Babel transform doing the aliasing at bundle time rather than the package manager.

This keeps your import statements platform-neutral and handles transitive dependencies automatically, so it’s the recommended approach for most apps.

How to set up the VMRP

1. Install the VMRP:

npm install --save-dev "@amazon-devices/kepler-module-resolver-preset"

Enter fullscreen mode Exit fullscreen mode

2. Install the babel-plugin-module-resolver:

npm install --save-dev "babel-plugin-module-resolver"

Enter fullscreen mode Exit fullscreen mode

3. Install both the original library and the Vega fork at their exact pinned versions. Check the Supported Libraries documentation for the correct pair:

npm install --save-exact [email protected]
npm install @amazon-devices/[email protected]

Enter fullscreen mode Exit fullscreen mode

Use --save-exact for the upstream library because VMRP compares the version string in your package.json character-for-character against the fork’s alias target. Without it, npm writes a ^ prefix that prevents the exact match.

4. Register the preset in your Babel config (.babelrc or babel.config.js, in the same folder as your package.json):

module.exports = {
    presets: [
        'module:metro-react-native-babel-preset',
        'module:@amazon-devices/kepler-module-resolver-preset', // Enables the Vega Module Resolver Preset
        ...
    ],
};

Enter fullscreen mode Exit fullscreen mode

5. Clean and re-build your package. You can now import the library by its original name, and it will be swapped for the fork automatically. A successful swap logs a confirmation line in the build output (Mapped react-native-svg to @amazon-devices/react-native-svg@...) and the native manifest will list the corresponding com.amazon.kepler.* system module dependency. If something goes wrong, you’ll see a Skipped warning instead (see Troubleshooting below).

The @amazon-devices/ packages are published on npm. Install them with npm install like any other dependency. Always pull the exact fork version from the Supported Libraries documentation because a mismatched pin causes VMRP to silently skip the swap.

Troubleshooting

Version mismatch

The VMRP requires an exact upstream version match. A caret/tilde range or the wrong version means it silently skips the library rather than mapping it. You’ll see a Skipped warning in the build output:

[kepler-module-resolver] Skipped react-native-svg, Version Mismatch! Application requested import react-native-svg@^13.14.0, aliased library is: @amazon-devices/[email protected]. An exact match is required.

Enter fullscreen mode Exit fullscreen mode

Note the ^ in the requested version above: a range prevents the exact match. Pin the original library to the plain upstream version ("react-native-svg": "13.14.0", not "^13.14.0") so it exactly matches what the fork aliases. If you used npm install without --save-exact, edit the version in package.json to remove the ^ and run npm install again to update the lockfile.

How to verify the swap succeeded

Grep the build output for [kepler-module-resolver]. A Mapped <library> line confirms the swap succeeded. A Skipped line means it didn’t. Check for a version mismatch as described above. If a library redboxes at runtime with an error like “RNSVGPath was not found in the UIManager” and you don’t see a Mapped line for it, the swap didn’t happen.

Parent library incompatible with the fork’s version

VMRP handling a transitive dependency doesn’t guarantee the parent library works end-to-end on Vega. The parent library may depend on a newer version of the upstream package than what the Vega fork currently targets. For example, if a library requires react-native-svg@^15.0.0 but the Vega fork aliases 13.14.0, pinning to 13.14.0 satisfies VMRP but may break the parent library (it could use APIs only available in v15). Check the reactnative.directory Vega filter to confirm a library has been validated on Vega, and test it yourself before shipping it in production.