Import Libraries in Your App with VMRP

You can use the Vega Module Resolver Preset (VMRP) to import libraries in your app. The preset replaces 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. Vega implements split bundling by default, and the JavaScript bundling doesn’t support standard npm aliases and overrides. VMRP provides an aliasing solution to ensure proper module resolution in this split bundle architecture. The Vega app template for React Native 0.83 doesn’t include VMRP. New apps, and apps migrated with the React Native 0.83 migration guide, import the Vega ported libraries directly. Add VMRP only if you want to keep the upstream import names for the ported libraries that still support it. Without this preset, you have to import Vega ported equivalencies of existing libraries. For example, if your app uses @react-native-async-storage/async-storage and you want to use this on Vega, you need to add this line to your code for the Vega version of the library:

import AsyncStorage from '@amazon-devices/react-native-async-storage__async-storage';

With VMRP, the import names can continue to be used as from '@react-native-async-storage/async-storage' and at bundle-time, the library will be swapped out.

About the preset

The VMRP walks through the node_modules of the package using it, constructing the relationship between Vega-ported packages and the equivalent library being requested by your application. A Vega-ported package supports VMRP only if its package.json declares the upstream package it replaces, in its kepler field. To check a package, run npm view <package>@<version> kepler. If the command prints nothing, the package doesn’t support VMRP, and you must import it directly. For example, npm view @amazon-devices/react-native-gesture-handler@4.0.1 kepler prints nothing. If the versions are equivalent, a mapping is established and the relationship is logged in the output. If the versions are not equivalent, or the module resolver fails for any other reason, error outputs will be logged.

Installation

The VMRP is distributed as a separate NPM package. To install, run the following command.

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

Additionally, you should include babel-plugin-module-resolver with this command.

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

Additionally, you need to install both the original third-party library and its Vega-ported library equivalent. For example, if you want to replace async storage with its Vega-equivalent library, you must install both packages in your package.json dependencies with their exact version, as shown below. For the versions that match each Vega-ported library, see Supported Libraries and Services.

"dependencies": {
  ...
  "@amazon-devices/react-native-async-storage__async-storage": "~2.1.0",
  "@react-native-async-storage/async-storage": "1.23.1",
  ...
}

Setup

After installation, you need to let babel know that you have a new preset you want to use when building your code, which is done via a change to Babel’s configuration file. Generally, this is either a .babelrc or babel.config.js found in the same folder as your package.json file:

module.exports = {
    presets: [
        'module:@react-native/babel-preset',
        'module:@amazon-devices/kepler-module-resolver-preset', // Enables usage of VegaModuleResolverPreset
        ...
    ],
    ...
  };

After that, you should clean and re-build your package. If the module replacement was successful, you will see output in your logs that indicates a library was swapped, for example:

[stdout] transform: [kepler-module-resolver] Mapped <LibraryNameHere> to <VegaPortedLibraryNameHere>@<Version>

​About the preset

​Installation

​Setup

About the preset

Installation

Setup