How to use the Vega Module Resolver Preset (VMRP)

Vega Open Beta Knowledge Base
1

Vega 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 as part of the @amazon-devices/ namespace, and we’ve also built the Vega Module Resolver Preset (VMRP), which replaces third-party libraries with their Vega-platform ported equivalencies.

Do I need the VMRP?

If your Vega app uses no third party libraries, or just forked libraries in the @amazon-devices/ namespace, or only pure JavaScript libraries, you won’t need it.

See How to Use React Native Libraries in Your Vega App for more details.

That said, we recommend using it in most Vega apps. It handles cases you might not anticipate, like transitive dependencies inside libraries you can’t edit.

What is the VMRP?

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"
  1. Install the babel-plugin-module-resolver:
npm install --save-dev "babel-plugin-module-resolver"
  1. 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 react-native-gesture-handler@2.13.0
npm install @amazon-devices/react-native-gesture-handler@2.0.1759135970

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.

  1. 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
        ...
    ],
};
  1. 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/react-native-svg@13.14.0. An exact match is required.

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.

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.

Please see our guide to How to Use React Native Libraries in Your Vega App for more info:

Last updated: July 20, 2026

How to Use React Native Libraries in Your Vega App